keyv 5.3.4 → 5.5.0

package/README.md

@@ -49,18 +49,12 @@ There are a few existing modules similar to Keyv, however Keyv is different beca
 	- [.setMany(entries)](#setmanyentries)
 	- [.get(key, [options])](#getkey-options)
 	- [.getMany(keys, [options])](#getmanykeys-options)
+  - [.getRaw(key)](#getrawkey)
+  - [.getManyRaw(keys)](#getmanyrawkeys)
 	- [.delete(key)](#deletekey)
 	- [.deleteMany(keys)](#deletemanykeys)
 	- [.clear()](#clear)
 	- [.iterator()](#iterator)
-- [API - Properties](#api---properties)
-  - [.namespace](#namespace-1)
-  - [.ttl](#ttl-1)
-  - [.store](#store-1)
-  - [.serialize](#serialize-1)
-  - [.deserialize](#deserialize-1)
-  - [.compression](#compression-1)
-  - [.useKeyPrefix](#usekeyprefix-1)
 - [How to Contribute](#how-to-contribute)
 - [License](#license)
 
@@ -83,6 +77,7 @@ npm install --save @keyv/postgres
 npm install --save @keyv/mysql
 npm install --save @keyv/etcd
 npm install --save @keyv/memcache
+npm install --save @keyv/dynamo
 ```
 
 First, create a new Keyv instance. 
@@ -233,7 +228,7 @@ keyv.hooks.addHandler(KeyvHooks.PRE_SET, (data) => console.log(`Setting key ${da
 
 //POST_SET hook
 const keyv = new Keyv();
-keyv.hooks.addHandler(KeyvHooks.POST_SET, (key, value) => console.log(`Set key ${key} to ${value}`));
+keyv.hooks.addHandler(KeyvHooks.POST_SET, ({key, value}) => console.log(`Set key ${key} to ${value}`));
 ```
 
 In these examples you can also manipulate the value before it is set. For example, you could add a prefix to all keys.
@@ -286,6 +281,7 @@ PostgreSQL | [@keyv/postgres](https://github.com/jaredwray/keyv/tree/master/pack
 MySQL | [@keyv/mysql](https://github.com/jaredwray/keyv/tree/master/packages/mysql) | No 
 Etcd | [@keyv/etcd](https://github.com/jaredwray/keyv/tree/master/packages/etcd) | Yes
 Memcache | [@keyv/memcache](https://github.com/jaredwray/keyv/tree/master/packages/memcache) | Yes
+DynamoDB | [@keyv/dynamo](https://github.com/jaredwray/keyv/tree/master/packages/dynamo) | Yes 
 
 # Third-party Storage Adapters
 
@@ -318,7 +314,6 @@ The following are third-party storage adapters compatible with Keyv:
 
 - [quick-lru](https://github.com/sindresorhus/quick-lru) - Simple "Least Recently Used" (LRU) cache
 - [keyv-file](https://github.com/zaaack/keyv-file) - File system storage adapter for Keyv
-- [keyv-dynamodb](https://www.npmjs.com/package/keyv-dynamodb) - DynamoDB storage adapter for Keyv
 - [keyv-lru](https://www.npmjs.com/package/keyv-lru) - LRU storage adapter for Keyv
 - [keyv-null](https://www.npmjs.com/package/keyv-null) - Null storage adapter for Keyv
 - [keyv-firestore ](https://github.com/goto-bus-stop/keyv-firestore) – Firebase Cloud Firestore adapter for Keyv
@@ -476,7 +471,7 @@ Returns a promise which resolves to the retrieved value.
 
 Returns a promise which resolves to an array of retrieved values.
 
-### options.raw
+### options.raw - (Will be deprecated in v6)
 
 Type: `Boolean`<br />
 Default: `false`
@@ -485,6 +480,16 @@ If set to true the raw DB object Keyv stores internally will be returned instead
 
 This contains the TTL timestamp.
 
+NOTE: This option will be deprecated in v6 and replaced with `.getRaw()` and `.getManyRaw()` methods.
+
+## .getRaw(key)
+
+Returns a promise which resolves to the raw stored data for the key or `undefined` if the key does not exist or is expired.
+
+## .getManyRaw(keys)
+
+Returns a promise which resolves to an array of raw stored data for the keys or `undefined` if the key does not exist or is expired.
+
 ## .delete(key)
 
 Deletes an entry.
@@ -623,6 +628,50 @@ keyv.useKeyPrefix = true;
 console.log(keyv.useKeyPrefix); // true
 ```
 
+With many of the storage adapters you will also need to set the `namespace` option to `undefined` to have it work correctly. This is because in `v5` we started the transition to having the storage adapter handle the namespacing and `Keyv` will no longer handle it internally via KeyPrefixing. Here is an example of doing ith with `KeyvSqlite`:
+
+```js
+import Keyv from 'keyv';
+import KeyvSqlite from '@keyv/sqlite';
+
+const store = new KeyvSqlite('sqlite://path/to/database.sqlite');
+const keyv = new Keyv({ store });
+keyv.useKeyPrefix = false; // disable key prefixing
+store.namespace = undefined; // disable namespacing in the storage adapter
+
+await keyv.set('foo', 'bar'); // true
+await keyv.get('foo'); // 'bar'
+await keyv.clear();
+```
+
+## .throwOnErrors
+
+Type: `Boolean`<br />
+Default: `false`
+
+If set to `true`, Keyv will throw an error if any operation fails. This is useful if you want to ensure that all operations are successful and you want to handle errors.
+
+```js
+const keyv = new Keyv({ throwOnErrors: true });
+console.log(keyv.throwOnErrors); // true
+keyv.throwOnErrors = false;
+console.log(keyv.throwOnErrors); // false
+```
+
+A good example of this is with the `@keyv/redis` storage adapter. If you want to handle connection errors, retries, and timeouts more gracefully, you can use the `throwOnErrors` option. This will throw an error if any operation fails, allowing you to catch it and handle it accordingly:
+
+```js
+import Keyv from 'keyv';
+import KeyvRedis from '@keyv/redis';
+
+// create redis instance that will throw on connection error
+const keyvRedis = new KeyvRedis('redis://user:pass@localhost:6379', { throwOnConnectErrors: true });
+
+const keyv = new Keyv({ store: keyvRedis, throwOnErrors: true });
+```
+
+What this does is it only throw on connection errors with the Redis client.
+
 # How to Contribute
 
 We welcome contributions to Keyv! 🎉 Here are some guides to get you started with contributing:

package/dist/index.cjs

@@ -185,6 +185,15 @@ var StatsManager = class extends event_manager_default {
       this.deletes++;
     }
   }
+  hitsOrMisses(array) {
+    for (const item of array) {
+      if (item === void 0) {
+        this.miss();
+      } else {
+        this.hit();
+      }
+    }
+  }
   reset() {
     this.hits = 0;
     this.misses = 0;
@@ -203,6 +212,10 @@ var KeyvHooks = /* @__PURE__ */ ((KeyvHooks2) => {
   KeyvHooks2["POST_GET"] = "postGet";
   KeyvHooks2["PRE_GET_MANY"] = "preGetMany";
   KeyvHooks2["POST_GET_MANY"] = "postGetMany";
+  KeyvHooks2["PRE_GET_RAW"] = "preGetRaw";
+  KeyvHooks2["POST_GET_RAW"] = "postGetRaw";
+  KeyvHooks2["PRE_GET_MANY_RAW"] = "preGetManyRaw";
+  KeyvHooks2["POST_GET_MANY_RAW"] = "postGetManyRaw";
   KeyvHooks2["PRE_DELETE"] = "preDelete";
   KeyvHooks2["POST_DELETE"] = "postDelete";
   return KeyvHooks2;
@@ -237,6 +250,7 @@ var Keyv = class extends event_manager_default {
   _deserialize = import_serialize.defaultDeserialize;
   _compression;
   _useKeyPrefix = true;
+  _throwOnErrors = false;
   /**
    * Keyv Constructor
    * @param {KeyvStoreAdapter | KeyvOptions} store
@@ -293,6 +307,9 @@ var Keyv = class extends event_manager_default {
     if (this.opts.useKeyPrefix !== void 0) {
       this._useKeyPrefix = this.opts.useKeyPrefix;
     }
+    if (this.opts.throwOnErrors !== void 0) {
+      this._throwOnErrors = this.opts.throwOnErrors;
+    }
   }
   /**
    * Get the current store
@@ -417,6 +434,21 @@ var Keyv = class extends event_manager_default {
     this._useKeyPrefix = value;
     this.opts.useKeyPrefix = value;
   }
+  /**
+   * Get the current throwErrors value. This will enable or disable throwing errors on methods in addition to emitting them.
+   * @return {boolean} The current throwOnErrors value.
+   */
+  get throwOnErrors() {
+    return this._throwOnErrors;
+  }
+  /**
+   * Set the current throwOnErrors value. This will enable or disable throwing errors on methods in addition to emitting them.
+   * @param {boolean} value The throwOnErrors value to set.
+   */
+  set throwOnErrors(value) {
+    this._throwOnErrors = value;
+    this.opts.throwOnErrors = value;
+  }
   generateIterator(iterator) {
     const function_ = async function* () {
       for await (const [key, raw] of typeof iterator === "function" ? iterator(this._store.namespace) : iterator) {
@@ -476,7 +508,14 @@ var Keyv = class extends event_manager_default {
       return this.getMany(key, { raw: false });
     }
     this.hooks.trigger("preGet" /* PRE_GET */, { key: keyPrefixed });
-    const rawData = await store.get(keyPrefixed);
+    let rawData;
+    try {
+      rawData = await store.get(keyPrefixed);
+    } catch (error) {
+      if (this.throwOnErrors) {
+        throw error;
+      }
+    }
     const deserializedData = typeof rawData === "string" || this.opts.compression ? await this.deserializeData(rawData) : rawData;
     if (deserializedData === void 0 || deserializedData === null) {
       this.stats.miss();
@@ -519,6 +558,7 @@ var Keyv = class extends event_manager_default {
     }
     const rawData = await store.getMany(keyPrefixed);
     const result = [];
+    const expiredKeys = [];
     for (const index in rawData) {
       let row = rawData[index];
       if (typeof row === "string") {
@@ -529,19 +569,96 @@ var Keyv = class extends event_manager_default {
         continue;
       }
       if (isDataExpired(row)) {
-        await this.delete(keys[index]);
+        expiredKeys.push(keys[index]);
         result.push(void 0);
         continue;
       }
       const value = options?.raw ? row : row.value;
       result.push(value);
     }
+    if (expiredKeys.length > 0) {
+      await this.deleteMany(expiredKeys);
+    }
     this.hooks.trigger("postGetMany" /* POST_GET_MANY */, result);
     if (result.length > 0) {
       this.stats.hit();
     }
     return result;
   }
+  /**
+   * Get the raw value of a key. This is the replacement for setting raw to true in the get() method.
+   * @param {string} key the key to get
+   * @returns {Promise<StoredDataRaw<Value> | undefined>} will return a StoredDataRaw<Value> or undefined if the key does not exist or is expired.
+   */
+  async getRaw(key) {
+    const { store } = this.opts;
+    const keyPrefixed = this._getKeyPrefix(key);
+    this.hooks.trigger("preGetRaw" /* PRE_GET_RAW */, { key: keyPrefixed });
+    const rawData = await store.get(keyPrefixed);
+    if (rawData === void 0 || rawData === null) {
+      this.stats.miss();
+      return void 0;
+    }
+    const deserializedData = typeof rawData === "string" || this.opts.compression ? await this.deserializeData(rawData) : rawData;
+    if (deserializedData !== void 0 && deserializedData.expires !== void 0 && deserializedData.expires !== null && deserializedData.expires < Date.now()) {
+      this.stats.miss();
+      await this.delete(key);
+      return void 0;
+    }
+    this.stats.hit();
+    this.hooks.trigger("postGetRaw" /* POST_GET_RAW */, { key: keyPrefixed, value: deserializedData });
+    return deserializedData;
+  }
+  /**
+   * Get the raw values of many keys. This is the replacement for setting raw to true in the getMany() method.
+   * @param {string[]} keys the keys to get
+   * @returns {Promise<Array<StoredDataRaw<Value>>>} will return an array of StoredDataRaw<Value> or undefined if the key does not exist or is expired.
+  */
+  async getManyRaw(keys) {
+    const { store } = this.opts;
+    const keyPrefixed = this._getKeyPrefixArray(keys);
+    if (keys.length === 0) {
+      const result2 = Array.from({ length: keys.length }).fill(void 0);
+      this.stats.misses += keys.length;
+      this.hooks.trigger("postGetManyRaw" /* POST_GET_MANY_RAW */, { keys: keyPrefixed, values: result2 });
+      return result2;
+    }
+    let result = [];
+    if (store.getMany === void 0) {
+      const promises = keyPrefixed.map(async (key) => {
+        const rawData = await store.get(key);
+        if (rawData !== void 0 && rawData !== null) {
+          return this.deserializeData(rawData);
+        }
+        return void 0;
+      });
+      const deserializedRows = await Promise.allSettled(promises);
+      result = deserializedRows.map((row) => row.value);
+    } else {
+      const rawData = await store.getMany(keyPrefixed);
+      for (const row of rawData) {
+        if (row !== void 0 && row !== null) {
+          result.push(await this.deserializeData(row));
+        } else {
+          result.push(void 0);
+        }
+      }
+    }
+    const expiredKeys = [];
+    const isDataExpired = (data) => typeof data.expires === "number" && Date.now() > data.expires;
+    for (const [index, row] of result.entries()) {
+      if (row !== void 0 && isDataExpired(row)) {
+        expiredKeys.push(keyPrefixed[index]);
+        result[index] = void 0;
+      }
+    }
+    if (expiredKeys.length > 0) {
+      await this.deleteMany(expiredKeys);
+    }
+    this.stats.hitsOrMisses(result);
+    this.hooks.trigger("postGetManyRaw" /* POST_GET_MANY_RAW */, { keys: keyPrefixed, values: result });
+    return result;
+  }
   /**
    * Set an item to the store
    * @param {string | Array<KeyvEntry>} key the key to use. If you pass in an array of KeyvEntry it will set many items
@@ -574,6 +691,9 @@ var Keyv = class extends event_manager_default {
     } catch (error) {
       result = false;
       this.emit("error", error);
+      if (this._throwOnErrors) {
+        throw error;
+      }
     }
     this.hooks.trigger("postSet" /* POST_SET */, { key: keyPrefixed, value: serializedValue, ttl });
     this.stats.set();
@@ -587,7 +707,14 @@ var Keyv = class extends event_manager_default {
   async setMany(entries) {
     let results = [];
     try {
-      if (this._store.setMany !== void 0) {
+      if (this._store.setMany === void 0) {
+        const promises = [];
+        for (const entry of entries) {
+          promises.push(this.set(entry.key, entry.value, entry.ttl));
+        }
+        const promiseResults = await Promise.all(promises);
+        results = promiseResults;
+      } else {
         const serializedEntries = await Promise.all(entries.map(async ({ key, value, ttl }) => {
           ttl ??= this._ttl;
           if (ttl === 0) {
@@ -604,14 +731,11 @@ var Keyv = class extends event_manager_default {
         }));
         results = await this._store.setMany(serializedEntries);
       }
-      const promises = [];
-      for (const entry of entries) {
-        promises.push(this.set(entry.key, entry.value, entry.ttl));
-      }
-      const promiseResults = await Promise.allSettled(promises);
-      results = promiseResults.map((result) => result.value);
     } catch (error) {
       this.emit("error", error);
+      if (this._throwOnErrors) {
+        throw error;
+      }
       results = entries.map(() => false);
     }
     return results;
@@ -637,6 +761,9 @@ var Keyv = class extends event_manager_default {
     } catch (error) {
       result = false;
       this.emit("error", error);
+      if (this._throwOnErrors) {
+        throw error;
+      }
     }
     this.hooks.trigger("postDelete" /* POST_DELETE */, { key: keyPrefixed, value: result });
     this.stats.delete();
@@ -656,12 +783,15 @@ var Keyv = class extends event_manager_default {
         return await store.deleteMany(keyPrefixed);
       }
       const promises = keyPrefixed.map(async (key) => store.delete(key));
-      const results = await Promise.allSettled(promises);
-      const returnResult = results.every((x) => x.value === true);
+      const results = await Promise.all(promises);
+      const returnResult = results.every(Boolean);
       this.hooks.trigger("postDelete" /* POST_DELETE */, { key: keyPrefixed, value: returnResult });
       return returnResult;
     } catch (error) {
       this.emit("error", error);
+      if (this._throwOnErrors) {
+        throw error;
+      }
       return false;
     }
   }
@@ -676,6 +806,9 @@ var Keyv = class extends event_manager_default {
       await store.clear();
     } catch (error) {
       this.emit("error", error);
+      if (this._throwOnErrors) {
+        throw error;
+      }
     }
   }
   async has(key) {
@@ -692,6 +825,10 @@ var Keyv = class extends event_manager_default {
       rawData = await store.get(keyPrefixed);
     } catch (error) {
       this.emit("error", error);
+      if (this._throwOnErrors) {
+        throw error;
+      }
+      return false;
     }
     if (rawData) {
       const data = await this.deserializeData(rawData);

package/dist/index.d.cts

@@ -37,6 +37,7 @@ declare class StatsManager extends EventManager {
     miss(): void;
     set(): void;
     delete(): void;
+    hitsOrMisses<T>(array: Array<T | undefined>): void;
     reset(): void;
 }
 
@@ -59,6 +60,10 @@ declare enum KeyvHooks {
     POST_GET = "postGet",
     PRE_GET_MANY = "preGetMany",
     POST_GET_MANY = "postGetMany",
+    PRE_GET_RAW = "preGetRaw",
+    POST_GET_RAW = "postGetRaw",
+    PRE_GET_MANY_RAW = "preGetManyRaw",
+    POST_GET_MANY_RAW = "postGetManyRaw",
     PRE_DELETE = "preDelete",
     POST_DELETE = "postDelete"
 }
@@ -102,24 +107,56 @@ type KeyvStoreAdapter = {
     iterator?<Value>(namespace?: string): AsyncGenerator<Array<string | Awaited<Value> | undefined>, void>;
 } & IEventEmitter;
 type KeyvOptions = {
-    /** Emit errors */
+    /**
+     * Emit errors
+     * @default true
+    */
     emitErrors?: boolean;
-    /** Namespace for the current instance. */
+    /**
+     * Namespace for the current instance.
+     * @default 'keyv'
+    */
     namespace?: string;
-    /** A custom serialization function. */
+    /**
+     * A custom serialization function.
+     * @default defaultSerialize using JSON.stringify
+     */
     serialize?: Serialize;
-    /** A custom deserialization function. */
+    /**
+     * A custom deserialization function.
+     * @default defaultDeserialize using JSON.parse
+    */
     deserialize?: Deserialize;
-    /** The storage adapter instance to be used by Keyv. */
+    /**
+     * The storage adapter instance to be used by Keyv.
+     * @default new Map() - in-memory store
+     */
     store?: KeyvStoreAdapter | Map<any, any> | any;
-    /** Default TTL. Can be overridden by specifying a TTL on `.set()`. */
+    /**
+     * Default TTL. Can be overridden by specifying a TTL on `.set()`.
+     * @default undefined
+     */
     ttl?: number;
-    /** Enable compression option **/
+    /**
+     * Enable compression option
+     * @default false
+     */
     compression?: CompressionAdapter | any;
-    /** Enable or disable statistics (default is false) */
+    /**
+     * Enable or disable statistics (default is false)
+     * @default false
+     */
     stats?: boolean;
-    /** Enable or disable key prefixing (default is true) */
+    /**
+     * Enable or disable key prefixing (default is true)
+     * @default true
+     */
     useKeyPrefix?: boolean;
+    /**
+     * Will enable throwing errors on methods in addition to emitting them.
+     * @default false
+     */
+    throwOnErrors?: boolean;
 };
 type KeyvOptions_ = Omit<KeyvOptions, 'store'> & {
     store: KeyvStoreAdapter | Map<any, any> & KeyvStoreAdapter;
@@ -146,6 +183,7 @@ declare class Keyv<GenericValue = any> extends EventManager {
     private _deserialize;
     private _compression;
     private _useKeyPrefix;
+    private _throwOnErrors;
     /**
      * Keyv Constructor
      * @param {KeyvStoreAdapter | KeyvOptions | Map<any, any>} store  to be provided or just the options
@@ -227,6 +265,16 @@ declare class Keyv<GenericValue = any> extends EventManager {
      * @param {boolean} value The useKeyPrefix value to set.
      */
     set useKeyPrefix(value: boolean);
+    /**
+     * Get the current throwErrors value. This will enable or disable throwing errors on methods in addition to emitting them.
+     * @return {boolean} The current throwOnErrors value.
+     */
+    get throwOnErrors(): boolean;
+    /**
+     * Set the current throwOnErrors value. This will enable or disable throwing errors on methods in addition to emitting them.
+     * @param {boolean} value The throwOnErrors value to set.
+     */
+    set throwOnErrors(value: boolean);
     generateIterator(iterator: IteratorFunction): IteratorFunction;
     _checkIterableAdapter(): boolean;
     _getKeyPrefix(key: string): string;
@@ -261,6 +309,18 @@ declare class Keyv<GenericValue = any> extends EventManager {
     getMany<Value = GenericValue>(keys: string[], options?: {
         raw: true;
     }): Promise<Array<StoredDataRaw<Value>>>;
+    /**
+     * Get the raw value of a key. This is the replacement for setting raw to true in the get() method.
+     * @param {string} key the key to get
+     * @returns {Promise<StoredDataRaw<Value> | undefined>} will return a StoredDataRaw<Value> or undefined if the key does not exist or is expired.
+     */
+    getRaw<Value = GenericValue>(key: string): Promise<StoredDataRaw<Value> | undefined>;
+    /**
+     * Get the raw values of many keys. This is the replacement for setting raw to true in the getMany() method.
+     * @param {string[]} keys the keys to get
+     * @returns {Promise<Array<StoredDataRaw<Value>>>} will return an array of StoredDataRaw<Value> or undefined if the key does not exist or is expired.
+    */
+    getManyRaw<Value = GenericValue>(keys: string[]): Promise<Array<StoredDataRaw<Value>>>;
     /**
      * Set an item to the store
      * @param {string | Array<KeyvEntry>} key the key to use. If you pass in an array of KeyvEntry it will set many items

package/dist/index.d.ts

@@ -37,6 +37,7 @@ declare class StatsManager extends EventManager {
     miss(): void;
     set(): void;
     delete(): void;
+    hitsOrMisses<T>(array: Array<T | undefined>): void;
     reset(): void;
 }
 
@@ -59,6 +60,10 @@ declare enum KeyvHooks {
     POST_GET = "postGet",
     PRE_GET_MANY = "preGetMany",
     POST_GET_MANY = "postGetMany",
+    PRE_GET_RAW = "preGetRaw",
+    POST_GET_RAW = "postGetRaw",
+    PRE_GET_MANY_RAW = "preGetManyRaw",
+    POST_GET_MANY_RAW = "postGetManyRaw",
     PRE_DELETE = "preDelete",
     POST_DELETE = "postDelete"
 }
@@ -102,24 +107,56 @@ type KeyvStoreAdapter = {
     iterator?<Value>(namespace?: string): AsyncGenerator<Array<string | Awaited<Value> | undefined>, void>;
 } & IEventEmitter;
 type KeyvOptions = {
-    /** Emit errors */
+    /**
+     * Emit errors
+     * @default true
+    */
     emitErrors?: boolean;
-    /** Namespace for the current instance. */
+    /**
+     * Namespace for the current instance.
+     * @default 'keyv'
+    */
     namespace?: string;
-    /** A custom serialization function. */
+    /**
+     * A custom serialization function.
+     * @default defaultSerialize using JSON.stringify
+     */
     serialize?: Serialize;
-    /** A custom deserialization function. */
+    /**
+     * A custom deserialization function.
+     * @default defaultDeserialize using JSON.parse
+    */
     deserialize?: Deserialize;
-    /** The storage adapter instance to be used by Keyv. */
+    /**
+     * The storage adapter instance to be used by Keyv.
+     * @default new Map() - in-memory store
+     */
     store?: KeyvStoreAdapter | Map<any, any> | any;
-    /** Default TTL. Can be overridden by specifying a TTL on `.set()`. */
+    /**
+     * Default TTL. Can be overridden by specifying a TTL on `.set()`.
+     * @default undefined
+     */
     ttl?: number;
-    /** Enable compression option **/
+    /**
+     * Enable compression option
+     * @default false
+     */
     compression?: CompressionAdapter | any;
-    /** Enable or disable statistics (default is false) */
+    /**
+     * Enable or disable statistics (default is false)
+     * @default false
+     */
     stats?: boolean;
-    /** Enable or disable key prefixing (default is true) */
+    /**
+     * Enable or disable key prefixing (default is true)
+     * @default true
+     */
     useKeyPrefix?: boolean;
+    /**
+     * Will enable throwing errors on methods in addition to emitting them.
+     * @default false
+     */
+    throwOnErrors?: boolean;
 };
 type KeyvOptions_ = Omit<KeyvOptions, 'store'> & {
     store: KeyvStoreAdapter | Map<any, any> & KeyvStoreAdapter;
@@ -146,6 +183,7 @@ declare class Keyv<GenericValue = any> extends EventManager {
     private _deserialize;
     private _compression;
     private _useKeyPrefix;
+    private _throwOnErrors;
     /**
      * Keyv Constructor
      * @param {KeyvStoreAdapter | KeyvOptions | Map<any, any>} store  to be provided or just the options
@@ -227,6 +265,16 @@ declare class Keyv<GenericValue = any> extends EventManager {
      * @param {boolean} value The useKeyPrefix value to set.
      */
     set useKeyPrefix(value: boolean);
+    /**
+     * Get the current throwErrors value. This will enable or disable throwing errors on methods in addition to emitting them.
+     * @return {boolean} The current throwOnErrors value.
+     */
+    get throwOnErrors(): boolean;
+    /**
+     * Set the current throwOnErrors value. This will enable or disable throwing errors on methods in addition to emitting them.
+     * @param {boolean} value The throwOnErrors value to set.
+     */
+    set throwOnErrors(value: boolean);
     generateIterator(iterator: IteratorFunction): IteratorFunction;
     _checkIterableAdapter(): boolean;
     _getKeyPrefix(key: string): string;
@@ -261,6 +309,18 @@ declare class Keyv<GenericValue = any> extends EventManager {
     getMany<Value = GenericValue>(keys: string[], options?: {
         raw: true;
     }): Promise<Array<StoredDataRaw<Value>>>;
+    /**
+     * Get the raw value of a key. This is the replacement for setting raw to true in the get() method.
+     * @param {string} key the key to get
+     * @returns {Promise<StoredDataRaw<Value> | undefined>} will return a StoredDataRaw<Value> or undefined if the key does not exist or is expired.
+     */
+    getRaw<Value = GenericValue>(key: string): Promise<StoredDataRaw<Value> | undefined>;
+    /**
+     * Get the raw values of many keys. This is the replacement for setting raw to true in the getMany() method.
+     * @param {string[]} keys the keys to get
+     * @returns {Promise<Array<StoredDataRaw<Value>>>} will return an array of StoredDataRaw<Value> or undefined if the key does not exist or is expired.
+    */
+    getManyRaw<Value = GenericValue>(keys: string[]): Promise<Array<StoredDataRaw<Value>>>;
     /**
      * Set an item to the store
      * @param {string | Array<KeyvEntry>} key the key to use. If you pass in an array of KeyvEntry it will set many items

package/dist/index.js

@@ -159,6 +159,15 @@ var StatsManager = class extends event_manager_default {
       this.deletes++;
     }
   }
+  hitsOrMisses(array) {
+    for (const item of array) {
+      if (item === void 0) {
+        this.miss();
+      } else {
+        this.hit();
+      }
+    }
+  }
   reset() {
     this.hits = 0;
     this.misses = 0;
@@ -177,6 +186,10 @@ var KeyvHooks = /* @__PURE__ */ ((KeyvHooks2) => {
   KeyvHooks2["POST_GET"] = "postGet";
   KeyvHooks2["PRE_GET_MANY"] = "preGetMany";
   KeyvHooks2["POST_GET_MANY"] = "postGetMany";
+  KeyvHooks2["PRE_GET_RAW"] = "preGetRaw";
+  KeyvHooks2["POST_GET_RAW"] = "postGetRaw";
+  KeyvHooks2["PRE_GET_MANY_RAW"] = "preGetManyRaw";
+  KeyvHooks2["POST_GET_MANY_RAW"] = "postGetManyRaw";
   KeyvHooks2["PRE_DELETE"] = "preDelete";
   KeyvHooks2["POST_DELETE"] = "postDelete";
   return KeyvHooks2;
@@ -211,6 +224,7 @@ var Keyv = class extends event_manager_default {
   _deserialize = defaultDeserialize;
   _compression;
   _useKeyPrefix = true;
+  _throwOnErrors = false;
   /**
    * Keyv Constructor
    * @param {KeyvStoreAdapter | KeyvOptions} store
@@ -267,6 +281,9 @@ var Keyv = class extends event_manager_default {
     if (this.opts.useKeyPrefix !== void 0) {
       this._useKeyPrefix = this.opts.useKeyPrefix;
     }
+    if (this.opts.throwOnErrors !== void 0) {
+      this._throwOnErrors = this.opts.throwOnErrors;
+    }
   }
   /**
    * Get the current store
@@ -391,6 +408,21 @@ var Keyv = class extends event_manager_default {
     this._useKeyPrefix = value;
     this.opts.useKeyPrefix = value;
   }
+  /**
+   * Get the current throwErrors value. This will enable or disable throwing errors on methods in addition to emitting them.
+   * @return {boolean} The current throwOnErrors value.
+   */
+  get throwOnErrors() {
+    return this._throwOnErrors;
+  }
+  /**
+   * Set the current throwOnErrors value. This will enable or disable throwing errors on methods in addition to emitting them.
+   * @param {boolean} value The throwOnErrors value to set.
+   */
+  set throwOnErrors(value) {
+    this._throwOnErrors = value;
+    this.opts.throwOnErrors = value;
+  }
   generateIterator(iterator) {
     const function_ = async function* () {
       for await (const [key, raw] of typeof iterator === "function" ? iterator(this._store.namespace) : iterator) {
@@ -450,7 +482,14 @@ var Keyv = class extends event_manager_default {
       return this.getMany(key, { raw: false });
     }
     this.hooks.trigger("preGet" /* PRE_GET */, { key: keyPrefixed });
-    const rawData = await store.get(keyPrefixed);
+    let rawData;
+    try {
+      rawData = await store.get(keyPrefixed);
+    } catch (error) {
+      if (this.throwOnErrors) {
+        throw error;
+      }
+    }
     const deserializedData = typeof rawData === "string" || this.opts.compression ? await this.deserializeData(rawData) : rawData;
     if (deserializedData === void 0 || deserializedData === null) {
       this.stats.miss();
@@ -493,6 +532,7 @@ var Keyv = class extends event_manager_default {
     }
     const rawData = await store.getMany(keyPrefixed);
     const result = [];
+    const expiredKeys = [];
     for (const index in rawData) {
       let row = rawData[index];
       if (typeof row === "string") {
@@ -503,19 +543,96 @@ var Keyv = class extends event_manager_default {
         continue;
       }
       if (isDataExpired(row)) {
-        await this.delete(keys[index]);
+        expiredKeys.push(keys[index]);
         result.push(void 0);
         continue;
       }
       const value = options?.raw ? row : row.value;
       result.push(value);
     }
+    if (expiredKeys.length > 0) {
+      await this.deleteMany(expiredKeys);
+    }
     this.hooks.trigger("postGetMany" /* POST_GET_MANY */, result);
     if (result.length > 0) {
       this.stats.hit();
     }
     return result;
   }
+  /**
+   * Get the raw value of a key. This is the replacement for setting raw to true in the get() method.
+   * @param {string} key the key to get
+   * @returns {Promise<StoredDataRaw<Value> | undefined>} will return a StoredDataRaw<Value> or undefined if the key does not exist or is expired.
+   */
+  async getRaw(key) {
+    const { store } = this.opts;
+    const keyPrefixed = this._getKeyPrefix(key);
+    this.hooks.trigger("preGetRaw" /* PRE_GET_RAW */, { key: keyPrefixed });
+    const rawData = await store.get(keyPrefixed);
+    if (rawData === void 0 || rawData === null) {
+      this.stats.miss();
+      return void 0;
+    }
+    const deserializedData = typeof rawData === "string" || this.opts.compression ? await this.deserializeData(rawData) : rawData;
+    if (deserializedData !== void 0 && deserializedData.expires !== void 0 && deserializedData.expires !== null && deserializedData.expires < Date.now()) {
+      this.stats.miss();
+      await this.delete(key);
+      return void 0;
+    }
+    this.stats.hit();
+    this.hooks.trigger("postGetRaw" /* POST_GET_RAW */, { key: keyPrefixed, value: deserializedData });
+    return deserializedData;
+  }
+  /**
+   * Get the raw values of many keys. This is the replacement for setting raw to true in the getMany() method.
+   * @param {string[]} keys the keys to get
+   * @returns {Promise<Array<StoredDataRaw<Value>>>} will return an array of StoredDataRaw<Value> or undefined if the key does not exist or is expired.
+  */
+  async getManyRaw(keys) {
+    const { store } = this.opts;
+    const keyPrefixed = this._getKeyPrefixArray(keys);
+    if (keys.length === 0) {
+      const result2 = Array.from({ length: keys.length }).fill(void 0);
+      this.stats.misses += keys.length;
+      this.hooks.trigger("postGetManyRaw" /* POST_GET_MANY_RAW */, { keys: keyPrefixed, values: result2 });
+      return result2;
+    }
+    let result = [];
+    if (store.getMany === void 0) {
+      const promises = keyPrefixed.map(async (key) => {
+        const rawData = await store.get(key);
+        if (rawData !== void 0 && rawData !== null) {
+          return this.deserializeData(rawData);
+        }
+        return void 0;
+      });
+      const deserializedRows = await Promise.allSettled(promises);
+      result = deserializedRows.map((row) => row.value);
+    } else {
+      const rawData = await store.getMany(keyPrefixed);
+      for (const row of rawData) {
+        if (row !== void 0 && row !== null) {
+          result.push(await this.deserializeData(row));
+        } else {
+          result.push(void 0);
+        }
+      }
+    }
+    const expiredKeys = [];
+    const isDataExpired = (data) => typeof data.expires === "number" && Date.now() > data.expires;
+    for (const [index, row] of result.entries()) {
+      if (row !== void 0 && isDataExpired(row)) {
+        expiredKeys.push(keyPrefixed[index]);
+        result[index] = void 0;
+      }
+    }
+    if (expiredKeys.length > 0) {
+      await this.deleteMany(expiredKeys);
+    }
+    this.stats.hitsOrMisses(result);
+    this.hooks.trigger("postGetManyRaw" /* POST_GET_MANY_RAW */, { keys: keyPrefixed, values: result });
+    return result;
+  }
   /**
    * Set an item to the store
    * @param {string | Array<KeyvEntry>} key the key to use. If you pass in an array of KeyvEntry it will set many items
@@ -548,6 +665,9 @@ var Keyv = class extends event_manager_default {
     } catch (error) {
       result = false;
       this.emit("error", error);
+      if (this._throwOnErrors) {
+        throw error;
+      }
     }
     this.hooks.trigger("postSet" /* POST_SET */, { key: keyPrefixed, value: serializedValue, ttl });
     this.stats.set();
@@ -561,7 +681,14 @@ var Keyv = class extends event_manager_default {
   async setMany(entries) {
     let results = [];
     try {
-      if (this._store.setMany !== void 0) {
+      if (this._store.setMany === void 0) {
+        const promises = [];
+        for (const entry of entries) {
+          promises.push(this.set(entry.key, entry.value, entry.ttl));
+        }
+        const promiseResults = await Promise.all(promises);
+        results = promiseResults;
+      } else {
         const serializedEntries = await Promise.all(entries.map(async ({ key, value, ttl }) => {
           ttl ??= this._ttl;
           if (ttl === 0) {
@@ -578,14 +705,11 @@ var Keyv = class extends event_manager_default {
         }));
         results = await this._store.setMany(serializedEntries);
       }
-      const promises = [];
-      for (const entry of entries) {
-        promises.push(this.set(entry.key, entry.value, entry.ttl));
-      }
-      const promiseResults = await Promise.allSettled(promises);
-      results = promiseResults.map((result) => result.value);
     } catch (error) {
       this.emit("error", error);
+      if (this._throwOnErrors) {
+        throw error;
+      }
       results = entries.map(() => false);
     }
     return results;
@@ -611,6 +735,9 @@ var Keyv = class extends event_manager_default {
     } catch (error) {
       result = false;
       this.emit("error", error);
+      if (this._throwOnErrors) {
+        throw error;
+      }
     }
     this.hooks.trigger("postDelete" /* POST_DELETE */, { key: keyPrefixed, value: result });
     this.stats.delete();
@@ -630,12 +757,15 @@ var Keyv = class extends event_manager_default {
         return await store.deleteMany(keyPrefixed);
       }
       const promises = keyPrefixed.map(async (key) => store.delete(key));
-      const results = await Promise.allSettled(promises);
-      const returnResult = results.every((x) => x.value === true);
+      const results = await Promise.all(promises);
+      const returnResult = results.every(Boolean);
       this.hooks.trigger("postDelete" /* POST_DELETE */, { key: keyPrefixed, value: returnResult });
       return returnResult;
     } catch (error) {
       this.emit("error", error);
+      if (this._throwOnErrors) {
+        throw error;
+      }
       return false;
     }
   }
@@ -650,6 +780,9 @@ var Keyv = class extends event_manager_default {
       await store.clear();
     } catch (error) {
       this.emit("error", error);
+      if (this._throwOnErrors) {
+        throw error;
+      }
     }
   }
   async has(key) {
@@ -666,6 +799,10 @@ var Keyv = class extends event_manager_default {
       rawData = await store.get(keyPrefixed);
     } catch (error) {
       this.emit("error", error);
+      if (this._throwOnErrors) {
+        throw error;
+      }
+      return false;
     }
     if (rawData) {
       const data = await this.deserializeData(rawData);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keyv",
-  "version": "5.3.4",
+  "version": "5.5.0",
   "description": "Simple key-value storage with support for multiple backends",
   "type": "module",
   "main": "dist/index.cjs",
@@ -54,23 +54,23 @@
   },
   "homepage": "https://github.com/jaredwray/keyv",
   "dependencies": {
-    "@keyv/serialize": "^1.0.3"
+    "@keyv/serialize": "^1.1.0"
   },
   "devDependencies": {
-    "@faker-js/faker": "^9.8.0",
-    "@vitest/coverage-v8": "^3.2.3",
+    "@faker-js/faker": "^9.9.0",
+    "@vitest/coverage-v8": "^3.2.4",
     "rimraf": "^6.0.1",
     "timekeeper": "^2.3.1",
     "tsd": "^0.32.0",
-    "vitest": "^3.2.3",
-    "xo": "^1.1.0",
-    "@keyv/compress-brotli": "^2.0.4",
+    "vitest": "^3.2.4",
+    "xo": "^1.2.0",
+    "@keyv/compress-brotli": "^2.0.5",
     "@keyv/compress-gzip": "^2.0.3",
-    "@keyv/sqlite": "^4.0.4",
-    "@keyv/memcache": "^2.0.1",
-    "@keyv/test-suite": "^2.0.7",
-    "@keyv/mongo": "^3.0.2",
-    "@keyv/compress-lz4": "^1.0.0"
+    "@keyv/memcache": "^2.0.2",
+    "@keyv/compress-lz4": "^1.0.1",
+    "@keyv/mongo": "^3.0.3",
+    "@keyv/sqlite": "^4.0.5",
+    "@keyv/test-suite": "^2.1.0"
   },
   "tsd": {
     "directory": "test"
@@ -82,7 +82,7 @@
   "scripts": {
     "build": "rimraf ./dist && tsup src/index.ts --format cjs,esm --dts --clean",
     "test": "xo --fix && vitest run --coverage",
-    "test:ci": "xo && vitest --run --sequence.setupFiles=list",
+    "test:ci": "xo && vitest --run --sequence.setupFiles=list --coverage",
     "clean": "rimraf ./node_modules ./coverage ./test/testdb.sqlite ./dist"
   }
 }