keyv 5.4.0 → 5.5.0

package/README.md

@@ -49,6 +49,8 @@ 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)
@@ -469,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`
@@ -478,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.

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;
@@ -572,6 +585,80 @@ var Keyv = class extends event_manager_default {
     }
     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

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"
 }
@@ -304,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"
 }
@@ -304,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;
@@ -546,6 +559,80 @@ var Keyv = class extends event_manager_default {
     }
     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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keyv",
-  "version": "5.4.0",
+  "version": "5.5.0",
   "description": "Simple key-value storage with support for multiple backends",
   "type": "module",
   "main": "dist/index.cjs",
@@ -63,14 +63,14 @@
     "timekeeper": "^2.3.1",
     "tsd": "^0.32.0",
     "vitest": "^3.2.4",
-    "xo": "^1.1.1",
-    "@keyv/memcache": "^2.0.2",
+    "xo": "^1.2.0",
+    "@keyv/compress-brotli": "^2.0.5",
     "@keyv/compress-gzip": "^2.0.3",
+    "@keyv/memcache": "^2.0.2",
     "@keyv/compress-lz4": "^1.0.1",
-    "@keyv/compress-brotli": "^2.0.5",
     "@keyv/mongo": "^3.0.3",
-    "@keyv/test-suite": "^2.0.9",
-    "@keyv/sqlite": "^4.0.5"
+    "@keyv/sqlite": "^4.0.5",
+    "@keyv/test-suite": "^2.1.0"
   },
   "tsd": {
     "directory": "test"