keyv 6.0.0-beta.3 → 6.0.0-beta.4

package/dist/index.cjs

@@ -177,6 +177,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
@@ -479,6 +499,12 @@ var KeyvBridgeAdapter = class extends hookified.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
@@ -486,9 +512,11 @@ var KeyvBridgeAdapter = class extends hookified.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 (this._storeHandlesNamespace) this._store.namespace = this._namespace;
 		if (typeof store.on === "function") store.on("error", (error) => this.emit("error", error));
 	}
 	/**
@@ -504,10 +532,15 @@ var KeyvBridgeAdapter = class extends hookified.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.
@@ -528,10 +561,12 @@ var KeyvBridgeAdapter = class extends hookified.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.
@@ -540,6 +575,7 @@ var KeyvBridgeAdapter = class extends hookified.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;
 	}
@@ -605,35 +641,49 @@ var KeyvBridgeAdapter = class extends hookified.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;
@@ -707,6 +757,10 @@ var KeyvBridgeAdapter = class extends hookified.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;
@@ -728,7 +782,7 @@ var KeyvBridgeAdapter = class extends hookified.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];
@@ -1168,6 +1222,29 @@ var KeyvStats = class {
 //#endregion
 //#region src/keyv.ts
 var Keyv = class Keyv extends hookified.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.
@@ -1207,29 +1284,6 @@ var Keyv = class Keyv extends hookified.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.
 	*/
@@ -1357,13 +1411,6 @@ var Keyv = class Keyv extends hookified.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.
@@ -1374,19 +1421,32 @@ var Keyv = class Keyv extends hookified.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("error", /* @__PURE__ */ new Error("Could not use the provided storage adapter, falling back to KeyvMemoryAdapter with Map"));
@@ -1444,13 +1504,27 @@ var Keyv = class Keyv extends hookified.Hookified {
 		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("before:getMany", { keys });
-		const rawData = await this._store.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) => {
@@ -1509,7 +1583,7 @@ var Keyv = class Keyv extends hookified.Hookified {
 			});
 			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) => {
@@ -1526,10 +1600,10 @@ var Keyv = class Keyv extends hookified.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;
@@ -1555,7 +1629,7 @@ var Keyv = class Keyv extends hookified.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("error", error);
@@ -1572,7 +1646,7 @@ var Keyv = class Keyv extends hookified.Hookified {
 	/**
 	* 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) => ({
@@ -1601,7 +1675,7 @@ var Keyv = class Keyv extends hookified.Hookified {
 				return {
 					key,
 					value: await this.encode(formattedValue),
-					ttl
+					expires
 				};
 			}));
 			const storeResult = await this._store.setMany(serializedEntries);
@@ -1626,7 +1700,7 @@ var Keyv = class Keyv extends hookified.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;
@@ -1636,11 +1710,12 @@ var Keyv = class Keyv extends hookified.Hookified {
 			value
 		};
 		await this.hookWithDeprecated("before:setRaw", data);
-		const ttl = ttlFromExpires(data.value.expires);
+		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;
@@ -1660,7 +1735,7 @@ var Keyv = class Keyv extends hookified.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) => ({
@@ -1672,11 +1747,10 @@ var Keyv = class Keyv extends hookified.Hookified {
 		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);
@@ -1716,7 +1790,7 @@ var Keyv = class Keyv extends hookified.Hookified {
 	/**
 	* 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 */
@@ -1769,7 +1843,7 @@ var Keyv = class Keyv extends hookified.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;
@@ -1792,8 +1866,9 @@ var Keyv = class Keyv extends hookified.Hookified {
 		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");
@@ -2009,10 +2084,14 @@ var KeyvMemoryAdapter = class extends hookified.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.
@@ -2089,24 +2168,24 @@ var KeyvMemoryAdapter = class extends hookified.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 = [];
@@ -2114,9 +2193,9 @@ var KeyvMemoryAdapter = class extends hookified.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;
@@ -2285,3 +2364,4 @@ exports.detectKeyvEncryption = detectKeyvEncryption;
 exports.detectKeyvSerialization = detectKeyvSerialization;
 exports.detectKeyvStorage = detectKeyvStorage;
 exports.jsonSerializer = jsonSerializer;
+exports.keyvStorageCapability = keyvStorageCapability;