keyv 6.0.0-beta.1 → 6.0.0-beta.4

package/dist/index.mjs

@@ -173,6 +173,26 @@ function detectKeyvStorage(obj) {
 	};
 }
 /**
+* Build the capability descriptor for a v6 storage adapter: the structurally detected
+* methods plus `expires: true`, declaring that the adapter accepts an absolute `expires`
+* timestamp on `set`/`setMany`. First-party adapters expose this from their `capabilities`
+* getter so Keyv uses them directly instead of bridging.
+* @param adapter - The storage adapter to describe (typically `this`).
+* @returns A {@link KeyvStorageCapability} with `expires` set to `true`.
+* @example
+* ```typescript
+* public get capabilities(): KeyvStorageCapability {
+*   return keyvStorageCapability(this);
+* }
+* ```
+*/
+function keyvStorageCapability(adapter) {
+	return {
+		...detectKeyvStorage(adapter),
+		expires: true
+	};
+}
+/**
 * Detect whether an object implements the Keyv compression adapter interface
 * @param obj - The object to check
 * @returns A {@link KeyvCompressionCapability} where `compatible` is `true` when both `compress` and `decompress` methods are present
@@ -402,26 +422,26 @@ async function deleteExpiredKeys(keys, data, keyv) {
 * Maps new hook names to their deprecated equivalents so both fire during migration.
 */
 const deprecatedHookAliases = new Map([
-	[KeyvHooks.BEFORE_SET, KeyvHooks.PRE_SET],
-	[KeyvHooks.AFTER_SET, KeyvHooks.POST_SET],
-	[KeyvHooks.BEFORE_GET, KeyvHooks.PRE_GET],
-	[KeyvHooks.AFTER_GET, KeyvHooks.POST_GET],
-	[KeyvHooks.BEFORE_GET_MANY, KeyvHooks.PRE_GET_MANY],
-	[KeyvHooks.AFTER_GET_MANY, KeyvHooks.POST_GET_MANY],
-	[KeyvHooks.BEFORE_GET_RAW, KeyvHooks.PRE_GET_RAW],
-	[KeyvHooks.AFTER_GET_RAW, KeyvHooks.POST_GET_RAW],
-	[KeyvHooks.BEFORE_GET_MANY_RAW, KeyvHooks.PRE_GET_MANY_RAW],
-	[KeyvHooks.AFTER_GET_MANY_RAW, KeyvHooks.POST_GET_MANY_RAW],
-	[KeyvHooks.BEFORE_SET_RAW, KeyvHooks.PRE_SET_RAW],
-	[KeyvHooks.AFTER_SET_RAW, KeyvHooks.POST_SET_RAW],
-	[KeyvHooks.BEFORE_SET_MANY, KeyvHooks.PRE_SET_MANY],
-	[KeyvHooks.AFTER_SET_MANY, KeyvHooks.POST_SET_MANY],
-	[KeyvHooks.BEFORE_SET_MANY_RAW, KeyvHooks.PRE_SET_MANY_RAW],
-	[KeyvHooks.AFTER_SET_MANY_RAW, KeyvHooks.POST_SET_MANY_RAW],
-	[KeyvHooks.BEFORE_DELETE, KeyvHooks.PRE_DELETE],
-	[KeyvHooks.AFTER_DELETE, KeyvHooks.POST_DELETE],
-	[KeyvHooks.BEFORE_DELETE_MANY, KeyvHooks.PRE_DELETE_MANY],
-	[KeyvHooks.AFTER_DELETE_MANY, KeyvHooks.POST_DELETE_MANY]
+	["before:set", "preSet"],
+	["after:set", "postSet"],
+	["before:get", "preGet"],
+	["after:get", "postGet"],
+	["before:getMany", "preGetMany"],
+	["after:getMany", "postGetMany"],
+	["before:getRaw", "preGetRaw"],
+	["after:getRaw", "postGetRaw"],
+	["before:getManyRaw", "preGetManyRaw"],
+	["after:getManyRaw", "postGetManyRaw"],
+	["before:setRaw", "preSetRaw"],
+	["after:setRaw", "postSetRaw"],
+	["before:setMany", "preSetMany"],
+	["after:setMany", "postSetMany"],
+	["before:setManyRaw", "preSetManyRaw"],
+	["after:setManyRaw", "postSetManyRaw"],
+	["before:delete", "preDelete"],
+	["after:delete", "postDelete"],
+	["before:deleteMany", "preDeleteMany"],
+	["after:deleteMany", "postDeleteMany"]
 ]);
 /**
 * Build the deprecated-hooks map used by Hookified to warn when old PRE_/POST_ hook names are registered.
@@ -475,6 +495,12 @@ var KeyvBridgeAdapter = class extends Hookified {
 	_keySeparator = ":";
 	_capabilities;
 	/**
+	* Whether the wrapped store manages its own namespace (exposes a `namespace` property).
+	* When true the bridge propagates its namespace to the store and does not prefix keys,
+	* so the store's native, namespace-scoped operations (notably `clear()`) are used directly.
+	*/
+	_storeHandlesNamespace;
+	/**
 	* Creates a new KeyvBridgeAdapter instance.
 	* @param store - The underlying promise-based store to bridge
 	* @param options - Configuration options for the adapter
@@ -482,10 +508,12 @@ var KeyvBridgeAdapter = class extends Hookified {
 	constructor(store, options) {
 		super({ throwOnHookError: false });
 		this._store = store;
+		this._capabilities = detectKeyvStorage(store);
+		this._storeHandlesNamespace = this._capabilities.store === "keyvStorage" && "namespace" in store;
 		if (options?.keySeparator) this._keySeparator = options.keySeparator;
 		if (options?.namespace) this._namespace = options.namespace;
-		this._capabilities = detectKeyvStorage(store);
-		if (typeof store.on === "function") store.on(KeyvEvents.ERROR, (error) => this.emit(KeyvEvents.ERROR, error));
+		if (this._storeHandlesNamespace) this._store.namespace = this._namespace;
+		if (typeof store.on === "function") store.on("error", (error) => this.emit("error", error));
 	}
 	/**
 	* Gets the underlying store instance.
@@ -500,10 +528,15 @@ var KeyvBridgeAdapter = class extends Hookified {
 		this._store = store;
 	}
 	/**
-	* Gets the detected capabilities of the underlying store.
+	* Gets the capabilities of the underlying store, with `expires: true` to declare that
+	* the bridge accepts an absolute `expires` timestamp (which it converts to a ttl for the
+	* wrapped legacy store).
 	*/
 	get capabilities() {
-		return this._capabilities;
+		return {
+			...this._capabilities,
+			expires: true
+		};
 	}
 	/**
 	* Gets the current key separator used between namespace and key.
@@ -524,10 +557,12 @@ var KeyvBridgeAdapter = class extends Hookified {
 		return this._namespace;
 	}
 	/**
-	* Sets the namespace.
+	* Sets the namespace. When the wrapped store manages its own namespace, the value is
+	* propagated to it so its native scoped operations stay in sync.
 	*/
 	set namespace(namespace) {
 		this._namespace = namespace;
+		if (this._storeHandlesNamespace) this._store.namespace = namespace;
 	}
 	/**
 	* Creates a prefixed key by combining the namespace and key with the separator.
@@ -536,6 +571,7 @@ var KeyvBridgeAdapter = class extends Hookified {
 	* @returns The prefixed key if namespace is provided, otherwise the original key
 	*/
 	getKeyPrefix(key, namespace) {
+		if (this._storeHandlesNamespace) return key;
 		if (namespace) return `${namespace}${this._keySeparator}${key}`;
 		return key;
 	}
@@ -601,35 +637,49 @@ var KeyvBridgeAdapter = class extends Hookified {
 		return values;
 	}
 	/**
-	* Stores a value in the store with an optional TTL.
+	* Stores a value in the store with an optional absolute expiry.
+	* The wrapped store's `set(key, value, ttl?)` expects a relative duration, so the absolute
+	* `expires` is converted to a remaining ttl (`undefined` when already expired or absent).
+	* The value is passed through unchanged — the bridge does not wrap it in an envelope — so
+	* expiry is enforced by the wrapped legacy store's own ttl handling. (The read-side
+	* {@link isDataExpired} check only fires when a caller stores a raw `{ value, expires }`
+	* object directly; when Keyv core drives the bridge the value arrives already encoded.)
 	* @param key - The key to store the value under
 	* @param value - The value to store
-	* @param ttl - Optional time-to-live in milliseconds
+	* @param expires - Optional absolute expiry as Unix ms since epoch
 	* @returns Always returns true indicating success
 	*/
-	async set(key, value, ttl) {
+	async set(key, value, expires) {
 		const keyPrefix = this.getKeyPrefix(key, this._namespace);
-		const result = await this._store.set(keyPrefix, value, ttl);
+		if (typeof expires === "number" && expires <= Date.now()) {
+			await this._store.delete(keyPrefix);
+			return true;
+		}
+		const result = await this._store.set(keyPrefix, value, ttlFromExpires(expires));
 		if (typeof result === "boolean") return result;
 		return true;
 	}
 	/**
 	* Stores multiple entries in the store at once.
 	* Delegates to the store's native setMany if available, otherwise loops over set.
-	* @param entries - Array of entries containing key, value, and optional TTL
+	* @param entries - Array of entries containing key, value, and optional absolute `expires`
 	*/
 	async setMany(entries) {
 		if (this._capabilities.methods.setMany.exists) {
-			const prefixedEntries = entries.map((entry) => ({
-				...entry,
-				key: this.getKeyPrefix(entry.key, this._namespace)
-			}));
-			await this._store.setMany?.(prefixedEntries);
+			const now = Date.now();
+			const isExpired = (entry) => typeof entry.expires === "number" && entry.expires <= now;
+			const live = entries.filter((entry) => !isExpired(entry));
+			if (live.length > 0) await this._store.setMany?.(live.map((entry) => ({
+				key: this.getKeyPrefix(entry.key, this._namespace),
+				value: entry.value,
+				ttl: ttlFromExpires(entry.expires)
+			})));
+			for (const entry of entries) if (isExpired(entry)) await this._store.delete(this.getKeyPrefix(entry.key, this._namespace));
 			return entries.map(() => true);
 		}
 		const results = [];
 		for (const entry of entries) {
-			await this.set(entry.key, entry.value, entry.ttl);
+			await this.set(entry.key, entry.value, entry.expires);
 			results.push(true);
 		}
 		return results;
@@ -692,7 +742,7 @@ var KeyvBridgeAdapter = class extends Hookified {
 			const result = await this._store.delete(keyPrefix);
 			results.push(result);
 		} catch (error) {
-			this.emit(KeyvEvents.ERROR, error);
+			this.emit("error", error);
 			results.push(false);
 		}
 		return results;
@@ -703,6 +753,10 @@ var KeyvBridgeAdapter = class extends Hookified {
 	* entire store is cleared.
 	*/
 	async clear() {
+		if (this._namespace && this._storeHandlesNamespace) {
+			await this._store.clear();
+			return;
+		}
 		if (!this._namespace || !this._capabilities.methods.iterator.exists) {
 			await this._store.clear();
 			return;
@@ -724,7 +778,7 @@ var KeyvBridgeAdapter = class extends Hookified {
 	async *iterator() {
 		if (!this._capabilities.methods.iterator.exists) return;
 		const namespace = this._namespace;
-		const prefix = namespace ? `${namespace}${this._keySeparator}` : void 0;
+		const prefix = namespace && !this._storeHandlesNamespace ? `${namespace}${this._keySeparator}` : void 0;
 		/* v8 ignore next -- @preserve */
 		for await (const entry of this._store.iterator?.(this._namespace) ?? []) {
 			const [key, data] = Array.isArray(entry) ? entry : [entry];
@@ -1164,6 +1218,29 @@ var KeyvStats = class {
 //#endregion
 //#region src/keyv.ts
 var Keyv = class Keyv extends Hookified {
+	/**
+	* Keyv Constructor
+	* @param {KeyvStorageAdapter | KeyvOptions} store
+	* @param {Omit<KeyvOptions, 'store'>} [options] if you provide the store you can then provide the Keyv Options
+	*/
+	constructor(store, options) {
+		const mergedOptions = Keyv.resolveOptions(store, options);
+		super({
+			throwOnHookError: false,
+			throwOnEmptyListeners: true,
+			throwOnEmitError: mergedOptions.throwOnErrors ?? false
+		});
+		this.deprecatedHooks = buildDeprecatedHooks();
+		this._compression = mergedOptions.compression;
+		this._encryption = mergedOptions.encryption;
+		this.initSerialization(mergedOptions);
+		this.initSanitize(mergedOptions);
+		this.initNamespace(mergedOptions.namespace);
+		this.initStats(mergedOptions);
+		if (mergedOptions.store) this.setStore(mergedOptions.store);
+		this.setTtl(mergedOptions.ttl);
+		this._checkExpired = mergedOptions.checkExpired ?? false;
+	}
 	/**
 	* Stats manager for tracking cache operation metrics (hits, misses, sets, deletes, errors).
 	* @default this is disabled.
@@ -1203,29 +1280,6 @@ var Keyv = class Keyv extends Hookified {
 	*/
 	_checkExpired = false;
 	/**
-	* Keyv Constructor
-	* @param {KeyvStorageAdapter | KeyvOptions} store
-	* @param {Omit<KeyvOptions, 'store'>} [options] if you provide the store you can then provide the Keyv Options
-	*/
-	constructor(store, options) {
-		const mergedOptions = Keyv.resolveOptions(store, options);
-		super({
-			throwOnHookError: false,
-			throwOnEmptyListeners: true,
-			throwOnEmitError: mergedOptions.throwOnErrors ?? false
-		});
-		this.deprecatedHooks = buildDeprecatedHooks();
-		this._compression = mergedOptions.compression;
-		this._encryption = mergedOptions.encryption;
-		this.initSerialization(mergedOptions);
-		this.initSanitize(mergedOptions);
-		this.initNamespace(mergedOptions.namespace);
-		this.initStats(mergedOptions);
-		if (mergedOptions.store) this.setStore(mergedOptions.store);
-		this.setTtl(mergedOptions.ttl);
-		this._checkExpired = mergedOptions.checkExpired ?? false;
-	}
-	/**
 	* Get the current storage adapter.
 	* @returns {KeyvStorageAdapter} The current storage adapter.
 	*/
@@ -1353,13 +1407,6 @@ var Keyv = class Keyv extends Hookified {
 		return this._stats;
 	}
 	/**
-	* When true, Keyv checks expiry at its layer on get/getMany/has/hasMany.
-	* When false (default), trusts the storage adapter.
-	*/
-	get checkExpired() {
-		return this._checkExpired;
-	}
-	/**
 	* Set the stats. When setting a new instance it will unsubscribe the old listeners
 	* and subscribe the new instance.
 	* @param {KeyvStats} stats The stats instance to set.
@@ -1370,22 +1417,35 @@ var Keyv = class Keyv extends Hookified {
 		this._stats.subscribe(this);
 	}
 	/**
-	* Resolves a store to a fully-compliant KeyvStorageAdapter using a 3-tier detection chain:
-	* 1. If the store already implements the full KeyvStorageAdapter interface, use it directly.
-	* 2. If the store is map-like (synchronous get/set/delete/has), wrap it in KeyvMemoryAdapter.
-	* 3. If the store has async get/set/delete/clear, wrap it in KeyvBridgeAdapter.
-	* 4. Otherwise, emit an error and fall back to a default in-memory KeyvMemoryAdapter.
+	* Get whether Keyv checks expiry at its own layer on get/getMany/has/hasMany.
+	* When false (default), it trusts the storage adapter to handle expiry.
+	* @returns {boolean} `true` if Keyv checks expiry at its layer.
+	*/
+	get checkExpired() {
+		return this._checkExpired;
+	}
+	/**
+	* Resolves a store to a fully-compliant KeyvStorageAdapter:
+	* 1. If the store declares the v6 `capabilities.expires` contract, use it directly (this takes
+	*    precedence over structural detection, so a full adapter whose async methods aren't written
+	*    with the `async` keyword is not mis-bridged).
+	* 2. If the store implements the full async storage interface (but doesn't declare `expires`),
+	*    treat it as a legacy relative-`ttl` adapter and wrap it in KeyvBridgeAdapter.
+	* 3. If the store is map-like (synchronous get/set/delete/has), wrap it in KeyvMemoryAdapter.
+	* 4. If the store has async get/set/delete/clear, wrap it in KeyvBridgeAdapter.
+	* 5. Otherwise, emit an error and fall back to a default in-memory KeyvMemoryAdapter.
 	*
 	* NOTE: this is used for internal but provided public for custom adapter testing
 	* @param {unknown} store The store to resolve.
 	* @returns {KeyvStorageAdapter} A fully-compliant storage adapter.
 	*/
 	resolveStore(store) {
+		if (store?.capabilities?.expires === true) return store;
 		const cap = detectKeyvStorage(store);
-		if (cap.store === "keyvStorage") return store;
+		if (cap.store === "keyvStorage") return new KeyvBridgeAdapter(store);
 		if (cap.store === "mapLike") return new KeyvMemoryAdapter(store);
 		if (cap.store === "asyncMap") return new KeyvBridgeAdapter(store);
-		this.emit(KeyvEvents.ERROR, /* @__PURE__ */ new Error("Could not use the provided storage adapter, falling back to KeyvMemoryAdapter with Map"));
+		this.emit("error", /* @__PURE__ */ new Error("Could not use the provided storage adapter, falling back to KeyvMemoryAdapter with Map"));
 		return new KeyvMemoryAdapter(/* @__PURE__ */ new Map());
 	}
 	/**
@@ -1395,7 +1455,7 @@ var Keyv = class Keyv extends Hookified {
 	*/
 	setStore(store) {
 		this._store = this.resolveStore(store);
-		if (typeof this._store.on === "function") this._store.on(KeyvEvents.ERROR, (error) => this.emit(KeyvEvents.ERROR, error));
+		if (typeof this._store.on === "function") this._store.on("error", (error) => this.emit("error", error));
 		this._store.namespace = this._namespace;
 	}
 	/**
@@ -1413,40 +1473,54 @@ var Keyv = class Keyv extends Hookified {
 		if (Array.isArray(key)) return this.getMany(key);
 		key = this._sanitize.enabled ? this._sanitize.cleanKey(key) : key;
 		if (key === "") return;
-		await this.hookWithDeprecated(KeyvHooks.BEFORE_GET, { key });
+		await this.hookWithDeprecated("before:get", { key });
 		let rawData;
 		try {
 			rawData = await this._store.get(key);
 		} catch (error) {
-			this.emit(KeyvEvents.ERROR, error);
-			this.emitTelemetry(KeyvEvents.STAT_ERROR, key);
+			this.emit("error", error);
+			this.emitTelemetry("stat:error", key);
 		}
 		let data;
 		if (this._checkExpired) [data] = await this.decodeWithExpire(key, rawData);
 		else data = rawData === void 0 || rawData === null ? void 0 : typeof rawData === "string" ? await this.decode(rawData) : rawData;
 		if (data === void 0) {
-			await this.hookWithDeprecated(KeyvHooks.AFTER_GET, {
+			await this.hookWithDeprecated("after:get", {
 				key,
 				value: void 0
 			});
-			this.emitTelemetry(KeyvEvents.STAT_MISS, key);
+			this.emitTelemetry("stat:miss", key);
 			return;
 		}
-		await this.hookWithDeprecated(KeyvHooks.AFTER_GET, {
+		await this.hookWithDeprecated("after:get", {
 			key,
 			value: data
 		});
-		this.emitTelemetry(KeyvEvents.STAT_HIT, key);
+		this.emitTelemetry("stat:hit", key);
 		return data.value;
 	}
 	/**
-	* Get many values of keys
-	* @param {string[]} keys passing in a single key or multiple as an array
+	* Reads many keys from the store, preferring its native `getMany` and falling back to parallel
+	* single `get`s when an adapter does not implement it. A directly-used v6 adapter is not
+	* structurally required to provide `getMany` (the bridge and memory adapters always do), so
+	* this keeps `getMany`/`getManyRaw` working regardless of the resolved adapter.
+	* @param keys - the keys to read
+	* @returns the raw store results in the same order as `keys`
+	*/
+	async storeGetMany(keys) {
+		if (typeof this._store.getMany === "function") return this._store.getMany(keys);
+		return Promise.all(keys.map(async (key) => this._store.get(key)));
+	}
+	/**
+	* Get many values for an array of keys.
+	* @param {string[]} keys the keys to get
+	* @returns {Promise<Array<Value | undefined>>} an array of values in the same order as the
+	* keys, with `undefined` for keys that do not exist or are expired.
 	*/
 	async getMany(keys) {
 		keys = this._sanitize.enabled ? this._sanitize.cleanKeys(keys) : keys;
-		await this.hookWithDeprecated(KeyvHooks.BEFORE_GET_MANY, { keys });
-		const rawData = await this._store.getMany(keys);
+		await this.hookWithDeprecated("before:getMany", { keys });
+		const rawData = await this.storeGetMany(keys);
 		let deserialized;
 		if (this._checkExpired) deserialized = await this.decodeWithExpire(keys, rawData);
 		else deserialized = await Promise.all(rawData.map(async (row) => {
@@ -1454,9 +1528,9 @@ var Keyv = class Keyv extends Hookified {
 			return typeof row === "string" ? this.decode(row) : row;
 		}));
 		const result = deserialized.map((row) => row !== void 0 ? row.value : void 0);
-		await this.hookWithDeprecated(KeyvHooks.AFTER_GET_MANY, result);
-		for (let i = 0; i < result.length; i++) if (result[i] === void 0) this.emitTelemetry(KeyvEvents.STAT_MISS, keys[i]);
-		else this.emitTelemetry(KeyvEvents.STAT_HIT, keys[i]);
+		await this.hookWithDeprecated("after:getMany", result);
+		for (let i = 0; i < result.length; i++) if (result[i] === void 0) this.emitTelemetry("stat:miss", keys[i]);
+		else this.emitTelemetry("stat:hit", keys[i]);
 		return result;
 	}
 	/**
@@ -1468,21 +1542,21 @@ var Keyv = class Keyv extends Hookified {
 	async getRaw(key) {
 		key = this._sanitize.enabled ? this._sanitize.cleanKey(key) : key;
 		if (key === "") return;
-		await this.hookWithDeprecated(KeyvHooks.BEFORE_GET_RAW, { key });
+		await this.hookWithDeprecated("before:getRaw", { key });
 		const rawData = await this._store.get(key);
 		let data;
 		if (this._checkExpired) [data] = await this.decodeWithExpire(key, rawData);
 		else data = rawData === void 0 || rawData === null ? void 0 : typeof rawData === "string" ? await this.decode(rawData) : rawData;
 		if (data === void 0) {
-			await this.hookWithDeprecated(KeyvHooks.AFTER_GET_RAW, {
+			await this.hookWithDeprecated("after:getRaw", {
 				key,
 				value: void 0
 			});
-			this.emitTelemetry(KeyvEvents.STAT_MISS, key);
+			this.emitTelemetry("stat:miss", key);
 			return;
 		}
-		this.emitTelemetry(KeyvEvents.STAT_HIT, key);
-		await this.hookWithDeprecated(KeyvHooks.AFTER_GET_RAW, {
+		this.emitTelemetry("stat:hit", key);
+		await this.hookWithDeprecated("after:getRaw", {
 			key,
 			value: data
 		});
@@ -1496,25 +1570,25 @@ var Keyv = class Keyv extends Hookified {
 	async getManyRaw(keys) {
 		/* v8 ignore next -- @preserve */
 		keys = this._sanitize.enabled ? this._sanitize.cleanKeys(keys) : keys;
-		await this.hookWithDeprecated(KeyvHooks.BEFORE_GET_MANY_RAW, { keys });
+		await this.hookWithDeprecated("before:getManyRaw", { keys });
 		if (keys.length === 0) {
 			const result = [];
-			await this.hookWithDeprecated(KeyvHooks.AFTER_GET_MANY_RAW, {
+			await this.hookWithDeprecated("after:getManyRaw", {
 				keys,
 				values: result
 			});
 			return result;
 		}
-		const rawData = await this._store.getMany(keys);
+		const rawData = await this.storeGetMany(keys);
 		let result;
 		if (this._checkExpired) result = await this.decodeWithExpire(keys, rawData);
 		else result = await Promise.all(rawData.map(async (row) => {
 			if (row === void 0 || row === null) return;
 			return typeof row === "string" ? this.decode(row) : row;
 		}));
-		for (let i = 0; i < result.length; i++) if (result[i] === void 0) this.emitTelemetry(KeyvEvents.STAT_MISS, keys[i]);
-		else this.emitTelemetry(KeyvEvents.STAT_HIT, keys[i]);
-		await this.hookWithDeprecated(KeyvHooks.AFTER_GET_MANY_RAW, {
+		for (let i = 0; i < result.length; i++) if (result[i] === void 0) this.emitTelemetry("stat:miss", keys[i]);
+		else this.emitTelemetry("stat:hit", keys[i]);
+		await this.hookWithDeprecated("after:getManyRaw", {
 			keys,
 			values: result
 		});
@@ -1522,10 +1596,10 @@ var Keyv = class Keyv extends Hookified {
 	}
 	/**
 	* Set an item to the store
-	* @param {string | Array<KeyvEntry<Value>>} key the key to use. If you pass in an array of KeyvEntry it will set many items
+	* @param {string} key the key to use
 	* @param {Value} value the value of the key
-	* @param {number} [ttl] time to live in milliseconds
-	* @returns {boolean} if it sets then it will return a true. On failure will return false.
+	* @param {number} [ttl] time to live in milliseconds. Overrides the instance-level `ttl`.
+	* @returns {Promise<boolean>} `true` if it was set successfully, `false` on failure.
 	*/
 	async set(key, value, ttl) {
 		key = this._sanitize.enabled ? this._sanitize.cleanKey(key) : key;
@@ -1535,12 +1609,12 @@ var Keyv = class Keyv extends Hookified {
 			value,
 			ttl
 		};
-		await this.hookWithDeprecated(KeyvHooks.BEFORE_SET, data);
+		await this.hookWithDeprecated("before:set", data);
 		data.ttl = resolveTtl(data.ttl, this._ttl);
 		const expires = calculateExpires(data.ttl);
 		if (typeof data.value === "symbol") {
-			this.emit(KeyvEvents.ERROR, "symbol cannot be serialized");
-			this.emitTelemetry(KeyvEvents.STAT_ERROR, key);
+			this.emit("error", "symbol cannot be serialized");
+			this.emitTelemetry("stat:error", key);
 			return false;
 		}
 		const formattedValue = {
@@ -1551,24 +1625,24 @@ var Keyv = class Keyv extends Hookified {
 		let encodedValue = formattedValue;
 		try {
 			encodedValue = await this.encode(formattedValue);
-			result = await this._store.set(data.key, encodedValue, data.ttl);
+			result = await this._store.set(data.key, encodedValue, expires);
 		} catch (error) {
 			result = false;
-			this.emit(KeyvEvents.ERROR, error);
-			this.emitTelemetry(KeyvEvents.STAT_ERROR, key);
+			this.emit("error", error);
+			this.emitTelemetry("stat:error", key);
 		}
-		await this.hookWithDeprecated(KeyvHooks.AFTER_SET, {
+		await this.hookWithDeprecated("after:set", {
 			key,
 			value: encodedValue,
 			ttl
 		});
-		if (result) this.emitTelemetry(KeyvEvents.STAT_SET, key);
+		if (result) this.emitTelemetry("stat:set", key);
 		return result;
 	}
 	/**
 	* Set many items to the store
 	* @param {Array<KeyvEntry<Value>>} entries the entries to set
-	* @returns {boolean[]} will return an array of booleans if it sets then it will return a true. On failure will return false.
+	* @returns {Promise<boolean[]>} an array of booleans, one per entry: `true` if set successfully, `false` on failure.
 	*/
 	async setMany(entries) {
 		entries = entries.map((e) => ({
@@ -1576,7 +1650,7 @@ var Keyv = class Keyv extends Hookified {
 			key: this._sanitize.enabled ? this._sanitize.cleanKey(e.key) : e.key
 		}));
 		const data = { entries };
-		await this.hookWithDeprecated(KeyvHooks.BEFORE_SET_MANY, data);
+		await this.hookWithDeprecated("before:setMany", data);
 		entries = data.entries;
 		let results = [];
 		try {
@@ -1586,8 +1660,8 @@ var Keyv = class Keyv extends Hookified {
 				const expires = calculateExpires(ttl);
 				/* v8 ignore next -- @preserve */
 				if (typeof value === "symbol") {
-					this.emit(KeyvEvents.ERROR, "symbol cannot be serialized");
-					this.emitTelemetry(KeyvEvents.STAT_ERROR, key);
+					this.emit("error", "symbol cannot be serialized");
+					this.emitTelemetry("stat:error", key);
 					throw new Error("symbol cannot be serialized");
 				}
 				const formattedValue = {
@@ -1597,19 +1671,19 @@ var Keyv = class Keyv extends Hookified {
 				return {
 					key,
 					value: await this.encode(formattedValue),
-					ttl
+					expires
 				};
 			}));
 			const storeResult = await this._store.setMany(serializedEntries);
 			/* v8 ignore next -- @preserve */
 			results = Array.isArray(storeResult) ? storeResult : entries.map(() => true);
-			this.emitTelemetry(KeyvEvents.STAT_SET, entries.map((e) => e.key));
+			this.emitTelemetry("stat:set", entries.map((e) => e.key));
 		} catch (error) {
-			this.emit(KeyvEvents.ERROR, error);
-			this.emitTelemetry(KeyvEvents.STAT_ERROR, entries.map((e) => e.key));
+			this.emit("error", error);
+			this.emitTelemetry("stat:error", entries.map((e) => e.key));
 			results = entries.map(() => false);
 		}
-		await this.hookWithDeprecated(KeyvHooks.AFTER_SET_MANY, {
+		await this.hookWithDeprecated("after:setMany", {
 			entries,
 			values: results
 		});
@@ -1622,7 +1696,7 @@ var Keyv = class Keyv extends Hookified {
 	* The store-level TTL is derived automatically from `value.expires`.
 	* @param {string} key the key to set
 	* @param {KeyvValue<Value>} value the raw value envelope to store
-	* @returns {boolean} if it sets then it will return a true. On failure will return false.
+	* @returns {Promise<boolean>} `true` if it was set successfully, `false` on failure.
 	*/
 	async setRaw(key, value) {
 		key = this._sanitize.enabled ? this._sanitize.cleanKey(key) : key;
@@ -1631,24 +1705,25 @@ var Keyv = class Keyv extends Hookified {
 			key,
 			value
 		};
-		await this.hookWithDeprecated(KeyvHooks.BEFORE_SET_RAW, data);
-		const ttl = ttlFromExpires(data.value.expires);
+		await this.hookWithDeprecated("before:setRaw", data);
+		const expires = data.value.expires;
+		const ttl = ttlFromExpires(expires);
 		let result = true;
 		try {
 			const encodedValue = await this.encode(data.value);
-			const storeResult = await this._store.set(data.key, encodedValue, ttl);
+			const storeResult = await this._store.set(data.key, encodedValue, expires);
 			if (typeof storeResult === "boolean") result = storeResult;
 		} catch (error) {
 			result = false;
-			this.emit(KeyvEvents.ERROR, error);
-			this.emitTelemetry(KeyvEvents.STAT_ERROR, key);
+			this.emit("error", error);
+			this.emitTelemetry("stat:error", key);
 		}
-		await this.hookWithDeprecated(KeyvHooks.AFTER_SET_RAW, {
+		await this.hookWithDeprecated("after:setRaw", {
 			key,
 			value: data.value,
 			ttl
 		});
-		if (result) this.emitTelemetry(KeyvEvents.STAT_SET, key);
+		if (result) this.emitTelemetry("stat:set", key);
 		return result;
 	}
 	/**
@@ -1656,33 +1731,33 @@ var Keyv = class Keyv extends Hookified {
 	* Each entry's value should be a KeyvValue object with { value, expires? }. If you need TTL-based expiration,
 	* set `expires` on each value directly. The store-level TTL is derived automatically from `value.expires`.
 	* @param {KeyvEntry<KeyvValue<Value>>[]} entries the raw entries to set
-	* @returns {boolean[]} will return an array of booleans if it sets then it will return a true. On failure will return false.
+	* @returns {Promise<boolean[]>} an array of booleans, one per entry: `true` if set successfully, `false` on failure.
 	*/
 	async setManyRaw(entries) {
 		entries = entries.map((e) => ({
 			...e,
+			/* v8 ignore next -- @preserve */
 			key: this._sanitize.enabled ? this._sanitize.cleanKey(e.key) : e.key
 		}));
 		let results = [];
-		await this.hookWithDeprecated(KeyvHooks.BEFORE_SET_MANY_RAW, { entries });
+		await this.hookWithDeprecated("before:setManyRaw", { entries });
 		try {
 			const rawEntries = await Promise.all(entries.map(async ({ key, value }) => {
-				const ttl = ttlFromExpires(value.expires);
 				return {
 					key,
 					value: await this.encode(value),
-					ttl
+					expires: value.expires
 				};
 			}));
 			const storeResult = await this._store.setMany(rawEntries);
 			results = Array.isArray(storeResult) ? storeResult : entries.map(() => true);
-			this.emitTelemetry(KeyvEvents.STAT_SET, entries.map((e) => e.key));
+			this.emitTelemetry("stat:set", entries.map((e) => e.key));
 		} catch (error) {
-			this.emit(KeyvEvents.ERROR, error);
-			this.emitTelemetry(KeyvEvents.STAT_ERROR, entries.map((e) => e.key));
+			this.emit("error", error);
+			this.emitTelemetry("stat:error", entries.map((e) => e.key));
 			results = entries.map(() => false);
 		}
-		await this.hookWithDeprecated(KeyvHooks.AFTER_SET_MANY_RAW, {
+		await this.hookWithDeprecated("after:setManyRaw", {
 			entries,
 			results
 		});
@@ -1692,46 +1767,46 @@ var Keyv = class Keyv extends Hookified {
 		if (Array.isArray(key)) return this.deleteMany(key);
 		key = this._sanitize.enabled ? this._sanitize.cleanKey(key) : key;
 		if (key === "") return false;
-		await this.hookWithDeprecated(KeyvHooks.BEFORE_DELETE, { key });
+		await this.hookWithDeprecated("before:delete", { key });
 		let result = true;
 		try {
 			result = await this._store.delete(key);
 		} catch (error) {
 			result = false;
-			this.emit(KeyvEvents.ERROR, error);
-			this.emitTelemetry(KeyvEvents.STAT_ERROR, key);
+			this.emit("error", error);
+			this.emitTelemetry("stat:error", key);
 		}
-		await this.hookWithDeprecated(KeyvHooks.AFTER_DELETE, {
+		await this.hookWithDeprecated("after:delete", {
 			key,
 			value: result
 		});
-		this.emitTelemetry(KeyvEvents.STAT_DELETE, key);
+		this.emitTelemetry("stat:delete", key);
 		return result;
 	}
 	/**
 	* Delete many items from the store
 	* @param {string[]} keys the keys to be deleted
-	* @returns {boolean[]} array of booleans indicating success for each key
+	* @returns {Promise<boolean[]>} an array of booleans indicating success for each key.
 	*/
 	async deleteMany(keys) {
 		/* v8 ignore next -- @preserve */
 		keys = this._sanitize.enabled ? this._sanitize.cleanKeys(keys) : keys;
-		await this.hookWithDeprecated(KeyvHooks.BEFORE_DELETE_MANY, { keys });
-		await this.hookWithDeprecated(KeyvHooks.BEFORE_DELETE, { key: keys });
+		await this.hookWithDeprecated("before:deleteMany", { keys });
+		await this.hookWithDeprecated("before:delete", { key: keys });
 		let results;
 		try {
 			results = await this._store.deleteMany(keys);
-			this.emitTelemetry(KeyvEvents.STAT_DELETE, keys);
+			this.emitTelemetry("stat:delete", keys);
 		} catch (error) {
-			this.emit(KeyvEvents.ERROR, error);
-			this.emitTelemetry(KeyvEvents.STAT_ERROR, keys);
+			this.emit("error", error);
+			this.emitTelemetry("stat:error", keys);
 			results = keys.map(() => false);
 		}
-		await this.hookWithDeprecated(KeyvHooks.AFTER_DELETE_MANY, {
+		await this.hookWithDeprecated("after:deleteMany", {
 			keys,
 			values: results
 		});
-		await this.hookWithDeprecated(KeyvHooks.AFTER_DELETE, {
+		await this.hookWithDeprecated("after:delete", {
 			key: keys,
 			value: results
 		});
@@ -1741,7 +1816,7 @@ var Keyv = class Keyv extends Hookified {
 		if (Array.isArray(key)) return this.hasMany(key);
 		key = this._sanitize.enabled ? this._sanitize.cleanKey(key) : key;
 		if (key === "") return false;
-		await this.hookWithDeprecated(KeyvHooks.BEFORE_HAS, { key });
+		await this.hookWithDeprecated("before:has", { key });
 		let result = false;
 		try {
 			if (this._checkExpired) {
@@ -1752,10 +1827,10 @@ var Keyv = class Keyv extends Hookified {
 				}
 			} else result = await this._store.has(key);
 		} catch (error) {
-			this.emit(KeyvEvents.ERROR, error);
-			this.emitTelemetry(KeyvEvents.STAT_ERROR, key);
+			this.emit("error", error);
+			this.emitTelemetry("stat:error", key);
 		}
-		await this.hookWithDeprecated(KeyvHooks.AFTER_HAS, {
+		await this.hookWithDeprecated("after:has", {
 			key,
 			value: result
 		});
@@ -1764,11 +1839,11 @@ var Keyv = class Keyv extends Hookified {
 	/**
 	* Check if many keys exist
 	* @param {string[]} keys the keys to check
-	* @returns {boolean[]} will return an array of booleans if the keys exist
+	* @returns {Promise<boolean[]>} an array of booleans in the same order as the keys, `true` if the key exists.
 	*/
 	async hasMany(keys) {
 		keys = this._sanitize.enabled ? this._sanitize.cleanKeys(keys) : keys;
-		await this.hookWithDeprecated(KeyvHooks.BEFORE_HAS_MANY, { keys });
+		await this.hookWithDeprecated("before:hasMany", { keys });
 		let results = [];
 		try {
 			if (this._checkExpired) {
@@ -1776,30 +1851,31 @@ var Keyv = class Keyv extends Hookified {
 				results = (await this.decodeWithExpire(keys, rawData)).map((row) => row !== void 0);
 			} else results = await this._store.hasMany(keys);
 		} catch (error) {
-			this.emit(KeyvEvents.ERROR, error);
-			this.emitTelemetry(KeyvEvents.STAT_ERROR, keys);
+			this.emit("error", error);
+			this.emitTelemetry("stat:error", keys);
 			results = keys.map(() => false);
 		}
-		await this.hookWithDeprecated(KeyvHooks.AFTER_HAS_MANY, {
+		await this.hookWithDeprecated("after:hasMany", {
 			keys,
 			values: results
 		});
 		return results;
 	}
 	/**
-	* Clear the store
-	* @returns {void}
+	* Clear the store. If a namespace is set only entries in that namespace are removed.
+	* Emits a `clear` event.
+	* @returns {Promise<void>} resolves once the entries have been cleared.
 	*/
 	async clear() {
 		this.emit("clear");
-		await this.hook(KeyvHooks.BEFORE_CLEAR, { namespace: this._namespace });
+		await this.hook("before:clear", { namespace: this._namespace });
 		try {
 			await this._store.clear();
 		} catch (error) {
-			this.emit(KeyvEvents.ERROR, error);
-			this.emitTelemetry(KeyvEvents.STAT_ERROR);
+			this.emit("error", error);
+			this.emitTelemetry("stat:error");
 		}
-		await this.hook(KeyvHooks.AFTER_CLEAR, { namespace: this._namespace });
+		await this.hook("after:clear", { namespace: this._namespace });
 	}
 	/**
 	* Will disconnect the store. This is only available if the store has a disconnect method
@@ -1807,13 +1883,13 @@ var Keyv = class Keyv extends Hookified {
 	*/
 	async disconnect() {
 		this.emit("disconnect");
-		await this.hook(KeyvHooks.BEFORE_DISCONNECT, { namespace: this._namespace });
+		await this.hook("before:disconnect", { namespace: this._namespace });
 		try {
 			if (this._store.disconnect) await this._store.disconnect();
 		} catch (error) {
-			this.emit(KeyvEvents.ERROR, error);
+			this.emit("error", error);
 		}
-		await this.hook(KeyvHooks.AFTER_DISCONNECT, { namespace: this._namespace });
+		await this.hook("after:disconnect", { namespace: this._namespace });
 	}
 	/**
 	* Iterate over all key-value pairs in the store. Automatically deserializes values,
@@ -1861,7 +1937,7 @@ var Keyv = class Keyv extends Hookified {
 			if (typeof result === "string") return await this._serialization.parse(result);
 			return result;
 		} catch (error) {
-			this.emit(KeyvEvents.ERROR, error);
+			this.emit("error", error);
 			return;
 		}
 	}
@@ -2004,10 +2080,14 @@ var KeyvMemoryAdapter = class extends Hookified {
 		if (options?.namespace) this._namespace = options?.namespace;
 	}
 	/**
-	* Gets the detected capabilities of the underlying store.
+	* Gets the capabilities of the underlying store, with `expires: true` to declare that
+	* this adapter accepts an absolute `expires` timestamp (the v6 storage contract).
 	*/
 	get capabilities() {
-		return this._capabilities;
+		return {
+			...this._capabilities,
+			expires: true
+		};
 	}
 	/**
 	* Gets the underlying store instance.
@@ -2084,24 +2164,24 @@ var KeyvMemoryAdapter = class extends Hookified {
 		return entry.value;
 	}
 	/**
-	* Stores a value in the store with an optional TTL.
+	* Stores a value in the store with an optional absolute expiry.
 	* @param key - The key to store the value under
 	* @param value - The value to store
-	* @param ttl - Optional time-to-live in milliseconds
+	* @param expires - Optional absolute expiry as Unix ms since epoch
 	* @returns Always returns true indicating success
 	*/
-	async set(key, value, ttl) {
+	async set(key, value, expires) {
 		const keyPrefix = this.getKeyPrefix(key, this._namespace);
 		const entry = {
 			value,
-			expires: ttl ? Date.now() + ttl : void 0
+			expires: typeof expires === "number" ? expires : void 0
 		};
-		this._store.set(keyPrefix, entry, ttl);
+		this._store.set(keyPrefix, entry, ttlFromExpires(expires));
 		return true;
 	}
 	/**
 	* Stores multiple entries in the store at once.
-	* @param entries - Array of entries containing key, value, and optional TTL
+	* @param entries - Array of entries containing key, value, and optional absolute `expires`
 	*/
 	async setMany(entries) {
 		const results = [];
@@ -2109,9 +2189,9 @@ var KeyvMemoryAdapter = class extends Hookified {
 			const keyPrefix = this.getKeyPrefix(entry.key, this._namespace);
 			const memEntry = {
 				value: entry.value,
-				expires: entry.ttl ? Date.now() + entry.ttl : void 0
+				expires: typeof entry.expires === "number" ? entry.expires : void 0
 			};
-			this._store.set(keyPrefix, memEntry, entry.ttl);
+			this._store.set(keyPrefix, memEntry, ttlFromExpires(entry.expires));
 			results.push(true);
 		}
 		return results;
@@ -2201,7 +2281,7 @@ var KeyvMemoryAdapter = class extends Hookified {
 			this._store.delete(keyPrefix);
 			results.push(existed);
 		} catch (error) {
-			this.emit(KeyvEvents.ERROR, error);
+			this.emit("error", error);
 			results.push(false);
 		}
 		return results;
@@ -2264,4 +2344,4 @@ function createKeyv(store, options) {
 	});
 }
 //#endregion
-export { Keyv, Keyv as default, KeyvBridgeAdapter, KeyvEvents, KeyvHooks, KeyvJsonSerializer, KeyvMemoryAdapter, KeyvSanitize, KeyvStats, createKeyv, detectKeyv, detectKeyvCompression, detectKeyvEncryption, detectKeyvSerialization, detectKeyvStorage, jsonSerializer };
+export { Keyv, Keyv as default, KeyvBridgeAdapter, KeyvEvents, KeyvHooks, KeyvJsonSerializer, KeyvMemoryAdapter, KeyvSanitize, KeyvStats, createKeyv, detectKeyv, detectKeyvCompression, detectKeyvEncryption, detectKeyvSerialization, detectKeyvStorage, jsonSerializer, keyvStorageCapability };