keyv 5.5.2 → 5.5.4

package/README.md

@@ -34,6 +34,7 @@ There are a few existing modules similar to Keyv, however Keyv is different beca
 - [Custom Serializers](#custom-serializers)
 - [Official Storage Adapters](#official-storage-adapters)
 - [Third-party Storage Adapters](#third-party-storage-adapters)
+- [Using BigMap to Scale](#using-bigmap-to-scale)
 - [Compression](#compression)
 - [API](#api)
   - [new Keyv([storage-adapter], [options]) or new Keyv([options])](#new-keyvstorage-adapter-options-or-new-keyvoptions)
@@ -44,6 +45,7 @@ There are a few existing modules similar to Keyv, however Keyv is different beca
   - [.deserialize](#deserialize)
   - [.compression](#compression)
   - [.useKeyPrefix](#usekeyprefix)
+  - [.stats](#stats)
   - [Keyv Instance](#keyv-instance)
 	- [.set(key, value, [ttl])](#setkey-value-ttl)
 	- [.setMany(entries)](#setmanyentries)
@@ -207,8 +209,12 @@ Keyv supports hooks for `get`, `set`, and `delete` methods. Hooks are useful for
 ```
 PRE_GET
 POST_GET
+PRE_GET_RAW
+POST_GET_RAW
 PRE_GET_MANY
 POST_GET_MANY
+PRE_GET_MANY_RAW
+POST_GET_MANY_RAW
 PRE_SET
 POST_SET
 PRE_DELETE
@@ -221,6 +227,37 @@ You can access this by importing `KeyvHooks` from the main Keyv package.
 import Keyv, { KeyvHooks } from 'keyv';
 ```
 
+## Get Hooks
+
+The `POST_GET` and `POST_GET_RAW` hooks fire on both cache hits and misses. When a cache miss occurs (key doesn't exist or is expired), the hooks receive `undefined` as the value.
+
+```js
+// POST_GET hook - fires on both hits and misses
+const keyv = new Keyv();
+keyv.hooks.addHandler(KeyvHooks.POST_GET, (data) => {
+  if (data.value === undefined) {
+    console.log(`Cache miss for key: ${data.key}`);
+  } else {
+    console.log(`Cache hit for key: ${data.key}`, data.value);
+  }
+});
+
+await keyv.get('existing-key'); // Logs cache hit with value
+await keyv.get('missing-key');  // Logs cache miss with undefined
+```
+
+```js
+// POST_GET_RAW hook - same behavior as POST_GET
+const keyv = new Keyv();
+keyv.hooks.addHandler(KeyvHooks.POST_GET_RAW, (data) => {
+  console.log(`Key: ${data.key}, Value:`, data.value);
+});
+
+await keyv.getRaw('foo'); // Logs with value or undefined
+```
+
+## Set Hooks
+
 ```js
 //PRE_SET hook
 const keyv = new Keyv();
@@ -244,6 +281,8 @@ keyv.hooks.addHandler(KeyvHooks.PRE_SET, (data) => {
 
 Now this key will have prefix- added to it before it is set.
 
+## Delete Hooks
+
 In `PRE_DELETE` and `POST_DELETE` hooks, the value could be a single item or an `Array`. This is based on the fact that `delete` can accept a single key or an `Array` of keys.
 
 
@@ -312,16 +351,78 @@ const keyv = new Keyv({ store: lru });
 
 The following are third-party storage adapters compatible with Keyv:
 
-- [quick-lru](https://github.com/sindresorhus/quick-lru) - Simple "Least Recently Used" (LRU) cache
+- [@resolid/keyv-sqlite](https://github.com/huijiewei/keyv-sqlite) - A new SQLite storage adapter for Keyv
+- [keyv-arango](https://github.com/TimMikeladze/keyv-arango) - ArangoDB storage adapter for Keyv
+- [keyv-azuretable](https://github.com/howlowck/keyv-azuretable) - Azure Table Storage/API adapter for Keyv
+- [keyv-browser](https://github.com/zaaack/keyv-browser) - Browser storage adapter for Keyv, including localStorage and indexedDB.
+- [keyv-cloudflare](https://npm.im/keyv-cloudflare) - Storage adapter for Cloudflare Workers KV
+- [keyv-dynamodb](https://www.npmjs.com/package/keyv-dynamodb) - DynamoDB storage adapter for Keyv
 - [keyv-file](https://github.com/zaaack/keyv-file) - File system 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
-- [keyv-mssql](https://github.com/pmorgan3/keyv-mssql) - Microsoft Sql Server adapter for Keyv
-- [keyv-azuretable](https://github.com/howlowck/keyv-azuretable) - Azure Table Storage/API adapter for Keyv
-- [keyv-arango](https://github.com/TimMikeladze/keyv-arango) - ArangoDB storage adapter for Keyv
+- [keyv-lru](https://www.npmjs.com/package/keyv-lru) - LRU storage adapter for Keyv
 - [keyv-momento](https://github.com/momentohq/node-keyv-adaptor/) - Momento storage adapter for Keyv
-- [@resolid/keyv-sqlite](https://github.com/huijiewei/keyv-sqlite) - A new SQLite storage adapter for Keyv
+- [keyv-mssql](https://github.com/pmorgan3/keyv-mssql) - Microsoft Sql Server adapter for Keyv
+- [keyv-null](https://www.npmjs.com/package/keyv-null) - Null storage adapter for Keyv
+- [keyv-upstash](https://github.com/mahdavipanah/keyv-upstash) - Upstash Redis adapter for Keyv
+- [quick-lru](https://github.com/sindresorhus/quick-lru) - Simple "Least Recently Used" (LRU) cache
+
+# Using BigMap to Scale
+
+## Understanding JavaScript Map Limitations
+
+JavaScript's built-in `Map` object has a practical limit of approximately **16.7 million entries** (2^24). When you try to store more entries than this limit, you'll encounter performance degradation or runtime errors. This limitation is due to how JavaScript engines internally manage Map objects.
+
+For applications that need to cache millions of entries in memory, this becomes a significant constraint. Common scenarios include:
+- High-traffic caching layers
+- Session stores for large-scale applications
+- In-memory data processing of large datasets
+- Real-time analytics with millions of data points
+
+## Why BigMap?
+
+`@keyv/bigmap` solves this limitation by using a **distributed hash approach** with multiple internal Map instances. Instead of storing all entries in a single Map, BigMap distributes entries across multiple Maps using a hash function. This allows you to scale beyond the 16.7 million entry limit while maintaining the familiar Map API.
+
+### Key Benefits:
+- **Scales beyond Map limits**: Store 20+ million entries without issues
+- **Map-compatible API**: Drop-in replacement for standard Map
+- **Performance**: Uses efficient DJB2 hashing for fast key distribution
+- **Type-safe**: Built with TypeScript and supports generics
+- **Customizable**: Configure store size and hash functions
+
+## Using BigMap with Keyv
+
+BigMap can be used directly with Keyv as a storage adapter, providing scalable in-memory storage with full TTL support.
+
+### Installation
+
+```bash
+npm install --save keyv @keyv/bigmap
+```
+
+### Basic Usage
+
+The simplest way to use BigMap with Keyv is through the `createKeyv` helper function:
+
+```js
+import { createKeyv } from '@keyv/bigmap';
+
+const keyv = createKeyv();
+
+// Set values with TTL (time in milliseconds)
+await keyv.set('user:1', { name: 'Alice', email: 'alice@example.com' }, 60000); // Expires in 60 seconds
+
+// Get values
+const user = await keyv.get('user:1');
+console.log(user); // { name: 'Alice', email: 'alice@example.com' }
+
+// Delete values
+await keyv.delete('user:1');
+
+// Clear all values
+await keyv.clear();
+```
+
+For more details about BigMap, see the [@keyv/bigmap documentation](https://github.com/jaredwray/keyv/tree/main/packages/bigmap).
 
 # Compression
 
@@ -672,6 +773,55 @@ const keyv = new Keyv({ store: keyvRedis, throwOnErrors: true });
 
 What this does is it only throw on connection errors with the Redis client.
 
+## .stats
+Type: `StatsManager`<br />
+Default: `StatsManager` instance with `enabled: false`
+
+The stats property provides access to statistics tracking for cache operations. When enabled via the `stats` option during initialization, it tracks hits, misses, sets, deletes, and errors.
+
+### Enabling Stats:
+```js
+const keyv = new Keyv({ stats: true });
+console.log(keyv.stats.enabled); // true
+```
+
+### Available Statistics:
+- `hits`: Number of successful cache retrievals
+- `misses`: Number of failed cache retrievals
+- `sets`: Number of set operations
+- `deletes`: Number of delete operations
+- `errors`: Number of errors encountered
+
+### Accessing Stats:
+```js
+const keyv = new Keyv({ stats: true });
+
+await keyv.set('foo', 'bar');
+await keyv.get('foo'); // cache hit
+await keyv.get('nonexistent'); // cache miss
+await keyv.delete('foo');
+
+console.log(keyv.stats.hits);    // 1
+console.log(keyv.stats.misses);  // 1
+console.log(keyv.stats.sets);    // 1
+console.log(keyv.stats.deletes); // 1
+```
+
+### Resetting Stats:
+```js
+keyv.stats.reset();
+console.log(keyv.stats.hits); // 0
+```
+
+### Manual Control:
+You can also manually enable/disable stats tracking at runtime:
+```js
+const keyv = new Keyv({ stats: false });
+keyv.stats.enabled = true; // Enable stats tracking
+// ... perform operations ...
+keyv.stats.enabled = false; // Disable stats tracking
+```
+
 # How to Contribute
 
 We welcome contributions to Keyv! 🎉 Here are some guides to get you started with contributing:

package/dist/index.cjs

@@ -394,14 +394,14 @@ var Keyv = class extends event_manager_default {
   }
   /**
    * Get the current TTL.
-   * @returns {number} The current TTL.
+   * @returns {number} The current TTL in milliseconds.
    */
   get ttl() {
     return this._ttl;
   }
   /**
    * Set the current TTL.
-   * @param {number} ttl The TTL to set.
+   * @param {number} ttl The TTL to set in milliseconds.
    */
   set ttl(ttl) {
     this.opts.ttl = ttl;
@@ -540,11 +540,19 @@ var Keyv = class extends event_manager_default {
     }
     const deserializedData = typeof rawData === "string" || this.opts.compression ? await this.deserializeData(rawData) : rawData;
     if (deserializedData === void 0 || deserializedData === null) {
+      this.hooks.trigger("postGet" /* POST_GET */, {
+        key: keyPrefixed,
+        value: void 0
+      });
       this.stats.miss();
       return void 0;
     }
     if (isDataExpired(deserializedData)) {
       await this.delete(key);
+      this.hooks.trigger("postGet" /* POST_GET */, {
+        key: keyPrefixed,
+        value: void 0
+      });
       this.stats.miss();
       return void 0;
     }
@@ -624,12 +632,20 @@ var Keyv = class extends event_manager_default {
     this.hooks.trigger("preGetRaw" /* PRE_GET_RAW */, { key: keyPrefixed });
     const rawData = await store.get(keyPrefixed);
     if (rawData === void 0 || rawData === null) {
+      this.hooks.trigger("postGetRaw" /* POST_GET_RAW */, {
+        key: keyPrefixed,
+        value: void 0
+      });
       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 && // biome-ignore lint/style/noNonNullAssertion: need to fix
     deserializedData.expires < Date.now()) {
+      this.hooks.trigger("postGetRaw" /* POST_GET_RAW */, {
+        key: keyPrefixed,
+        value: void 0
+      });
       this.stats.miss();
       await this.delete(key);
       return void 0;
@@ -776,7 +792,8 @@ var Keyv = class extends event_manager_default {
             }
             const formattedValue = { value, expires };
             const serializedValue = await this.serializeData(formattedValue);
-            return { key, value: serializedValue, ttl };
+            const keyPrefixed = this._getKeyPrefix(key);
+            return { key: keyPrefixed, value: serializedValue, ttl };
           })
         );
         results = await this._store.setMany(serializedEntries);
@@ -967,3 +984,4 @@ var index_default = Keyv;
   Keyv,
   KeyvHooks
 });
+/* v8 ignore next -- @preserve */

package/dist/index.d.cts

@@ -133,7 +133,7 @@ type KeyvOptions = {
      */
     store?: KeyvStoreAdapter | Map<any, any> | any;
     /**
-     * Default TTL. Can be overridden by specifying a TTL on `.set()`.
+     * Default TTL in milliseconds. Can be overridden by specifying a TTL on `.set()`.
      * @default undefined
      */
     ttl?: number;
@@ -226,12 +226,12 @@ declare class Keyv<GenericValue = any> extends EventManager {
     set namespace(namespace: string | undefined);
     /**
      * Get the current TTL.
-     * @returns {number} The current TTL.
+     * @returns {number} The current TTL in milliseconds.
      */
     get ttl(): number | undefined;
     /**
      * Set the current TTL.
-     * @param {number} ttl The TTL to set.
+     * @param {number} ttl The TTL to set in milliseconds.
      */
     set ttl(ttl: number | undefined);
     /**

package/dist/index.d.ts

@@ -133,7 +133,7 @@ type KeyvOptions = {
      */
     store?: KeyvStoreAdapter | Map<any, any> | any;
     /**
-     * Default TTL. Can be overridden by specifying a TTL on `.set()`.
+     * Default TTL in milliseconds. Can be overridden by specifying a TTL on `.set()`.
      * @default undefined
      */
     ttl?: number;
@@ -226,12 +226,12 @@ declare class Keyv<GenericValue = any> extends EventManager {
     set namespace(namespace: string | undefined);
     /**
      * Get the current TTL.
-     * @returns {number} The current TTL.
+     * @returns {number} The current TTL in milliseconds.
      */
     get ttl(): number | undefined;
     /**
      * Set the current TTL.
-     * @param {number} ttl The TTL to set.
+     * @param {number} ttl The TTL to set in milliseconds.
      */
     set ttl(ttl: number | undefined);
     /**

package/dist/index.js

@@ -368,14 +368,14 @@ var Keyv = class extends event_manager_default {
   }
   /**
    * Get the current TTL.
-   * @returns {number} The current TTL.
+   * @returns {number} The current TTL in milliseconds.
    */
   get ttl() {
     return this._ttl;
   }
   /**
    * Set the current TTL.
-   * @param {number} ttl The TTL to set.
+   * @param {number} ttl The TTL to set in milliseconds.
    */
   set ttl(ttl) {
     this.opts.ttl = ttl;
@@ -514,11 +514,19 @@ var Keyv = class extends event_manager_default {
     }
     const deserializedData = typeof rawData === "string" || this.opts.compression ? await this.deserializeData(rawData) : rawData;
     if (deserializedData === void 0 || deserializedData === null) {
+      this.hooks.trigger("postGet" /* POST_GET */, {
+        key: keyPrefixed,
+        value: void 0
+      });
       this.stats.miss();
       return void 0;
     }
     if (isDataExpired(deserializedData)) {
       await this.delete(key);
+      this.hooks.trigger("postGet" /* POST_GET */, {
+        key: keyPrefixed,
+        value: void 0
+      });
       this.stats.miss();
       return void 0;
     }
@@ -598,12 +606,20 @@ var Keyv = class extends event_manager_default {
     this.hooks.trigger("preGetRaw" /* PRE_GET_RAW */, { key: keyPrefixed });
     const rawData = await store.get(keyPrefixed);
     if (rawData === void 0 || rawData === null) {
+      this.hooks.trigger("postGetRaw" /* POST_GET_RAW */, {
+        key: keyPrefixed,
+        value: void 0
+      });
       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 && // biome-ignore lint/style/noNonNullAssertion: need to fix
     deserializedData.expires < Date.now()) {
+      this.hooks.trigger("postGetRaw" /* POST_GET_RAW */, {
+        key: keyPrefixed,
+        value: void 0
+      });
       this.stats.miss();
       await this.delete(key);
       return void 0;
@@ -750,7 +766,8 @@ var Keyv = class extends event_manager_default {
             }
             const formattedValue = { value, expires };
             const serializedValue = await this.serializeData(formattedValue);
-            return { key, value: serializedValue, ttl };
+            const keyPrefixed = this._getKeyPrefix(key);
+            return { key: keyPrefixed, value: serializedValue, ttl };
           })
         );
         results = await this._store.setMany(serializedEntries);
@@ -941,3 +958,4 @@ export {
   KeyvHooks,
   index_default as default
 };
+/* v8 ignore next -- @preserve */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keyv",
-  "version": "5.5.2",
+  "version": "5.5.4",
   "description": "Simple key-value storage with support for multiple backends",
   "type": "module",
   "main": "dist/index.cjs",
@@ -47,20 +47,20 @@
     "@keyv/serialize": "^1.1.1"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.2.3",
-    "@faker-js/faker": "^10.0.0",
-    "@vitest/coverage-v8": "^3.2.4",
-    "rimraf": "^6.0.1",
+    "@biomejs/biome": "^2.3.3",
+    "@faker-js/faker": "^10.1.0",
+    "@vitest/coverage-v8": "^4.0.6",
+    "rimraf": "^6.1.0",
     "timekeeper": "^2.3.1",
     "tsd": "^0.33.0",
-    "vitest": "^3.2.4",
+    "vitest": "^4.0.6",
     "@keyv/compress-brotli": "^2.0.5",
     "@keyv/compress-lz4": "^1.0.1",
-    "@keyv/mongo": "^3.0.3",
-    "@keyv/memcache": "^2.0.2",
     "@keyv/compress-gzip": "^2.0.3",
-    "@keyv/sqlite": "^4.0.5",
-    "@keyv/test-suite": "^2.1.1"
+    "@keyv/memcache": "^2.0.2",
+    "@keyv/sqlite": "^4.0.6",
+    "@keyv/test-suite": "^2.1.1",
+    "@keyv/mongo": "^3.0.5"
   },
   "tsd": {
     "directory": "test"