keyv 6.0.0-alpha.2 → 6.0.0-beta.1

package/README.md

@@ -4,6 +4,7 @@
 
 [![build](https://github.com/jaredwray/keyv/actions/workflows/tests.yaml/badge.svg)](https://github.com/jaredwray/keyv/actions/workflows/tests.yaml)
 [![bun](https://github.com/jaredwray/keyv/actions/workflows/bun-test.yaml/badge.svg)](https://github.com/jaredwray/keyv/actions/workflows/bun-test.yaml)
+[![browser](https://github.com/jaredwray/keyv/actions/workflows/browser-compat.yaml/badge.svg)](https://github.com/jaredwray/keyv/actions/workflows/browser-compat.yaml)
 [![codecov](https://codecov.io/gh/jaredwray/keyv/branch/main/graph/badge.svg?token=bRzR3RyOXZ)](https://codecov.io/gh/jaredwray/keyv)
 [![npm](https://img.shields.io/npm/dm/keyv.svg)](https://www.npmjs.com/package/keyv)
 [![npm](https://img.shields.io/npm/v/keyv.svg)](https://www.npmjs.com/package/keyv)
@@ -19,7 +20,7 @@ There are a few existing modules similar to Keyv, however Keyv is different beca
 - Suitable as a TTL based cache or persistent key-value store
 - [Easily embeddable](#add-cache-support-to-your-module) inside another module
 - Works with any storage that implements the [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) API
-- Handles all JSON types plus `Buffer`
+- Handles all JSON types plus `Buffer` and `BigInt` via the built-in `KeyvJsonSerializer`
 - Supports namespaces
 - Wide range of [**efficient, well tested**](#official-storage-adapters) storage adapters
 - Connection errors are passed through (db failures won't kill your app)
@@ -32,21 +33,24 @@ There are a few existing modules similar to Keyv, however Keyv is different beca
 - [Namespaces](#namespaces)
 - [Events](#events)
 - [Hooks](#hooks)
-- [Custom Serializers](#custom-serializers)
+- [Serialization](#serialization)
 - [Official Storage Adapters](#official-storage-adapters)
 - [Third-party Storage Adapters](#third-party-storage-adapters)
 - [Using BigMap to Scale](#using-bigmap-to-scale)
 - [Compression](#compression)
+- [Capability Detection](#capability-detection)
 - [API](#api)
   - [new Keyv([storage-adapter], [options]) or new Keyv([options])](#new-keyvstorage-adapter-options-or-new-keyvoptions)
   - [.namespace](#namespace)
   - [.ttl](#ttl)
   - [.store](#store)
-  - [.serialize](#serialize)
-  - [.deserialize](#deserialize)
+  - [.serialization](#serialization-1)
   - [.compression](#compression)
   - [.useKeyPrefix](#usekeyprefix)
+  - [.emitErrors](#emiterrors)
+  - [.throwOnErrors](#throwonerrors)
   - [.stats](#stats)
+  - [.sanitize](#sanitize)
   - [Keyv Instance](#keyv-instance)
 	- [.set(key, value, [ttl])](#setkey-value-ttl)
 	- [.setMany(entries)](#setmanyentries)
@@ -54,9 +58,14 @@ There are a few existing modules similar to Keyv, however Keyv is different beca
 	- [.getMany(keys, [options])](#getmanykeys-options)
   - [.getRaw(key)](#getrawkey)
   - [.getManyRaw(keys)](#getmanyrawkeys)
+  - [.setRaw(key, value)](#setrawkey-value)
+  - [.setManyRaw(entries)](#setmanyrawentries)
 	- [.delete(key)](#deletekey)
 	- [.deleteMany(keys)](#deletemanykeys)
 	- [.clear()](#clear)
+	- [.has(key)](#haskey)
+	- [.hasMany(keys)](#hasmanykeys)
+	- [.disconnect()](#disconnect)
 	- [.iterator()](#iterator)
 - [Bun Support](#bun-support)
 - [How to Contribute](#how-to-contribute)
@@ -219,6 +228,10 @@ PRE_GET_MANY_RAW
 POST_GET_MANY_RAW
 PRE_SET
 POST_SET
+PRE_SET_RAW
+POST_SET_RAW
+PRE_SET_MANY_RAW
+POST_SET_MANY_RAW
 PRE_DELETE
 POST_DELETE
 ```
@@ -288,41 +301,80 @@ Now this key will have prefix- added to it before it is set.
 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.
 
 
-# Custom Serializers
+# Serialization
 
-Keyv uses [`buffer`](https://nodejs.org/api/buffer.html) for data serialization to ensure consistency across different backends.
+By default, Keyv uses its built-in `KeyvJsonSerializer` — a JSON-based serializer with support for `Buffer` and `BigInt` types. This works out of the box with all storage adapters.
 
-You can optionally provide your own serialization functions to support extra data types or to serialize to something other than JSON.
+## Official Serializers
+
+In addition to the built-in serializer, Keyv offers two official serialization packages:
+
+### SuperJSON
+
+[`@keyv/serialize-superjson`](https://github.com/jaredwray/keyv/tree/main/serialization/superjson) supports `Date`, `RegExp`, `Map`, `Set`, `BigInt`, `undefined`, `Error`, and `URL` types.
 
 ```js
-const keyv = new Keyv({ serialize: JSON.stringify, deserialize: JSON.parse });
+import Keyv from 'keyv';
+import { superJsonSerializer } from '@keyv/serialize-superjson'; // using the helper function that does new KeyvSuperJsonSerializer()
+
+const keyv = new Keyv({ serialization: superJsonSerializer });
 ```
 
-**Warning:** Using custom serializers means you lose any guarantee of data consistency. You should do extensive testing with your serialisation functions and chosen storage engine.
+### MessagePack (msgpackr)
 
-If you do not want to use serialization you can set the `serialize` and `deserialize` functions to `undefined`. This will also turn off compression.
+[`@keyv/serialize-msgpackr`](https://github.com/jaredwray/keyv/tree/main/serialization/msgpackr) is a binary serializer that supports `Date`, `RegExp`, `Map`, `Set`, `Error`, `undefined`, `NaN`, and `Infinity` types.
 
 ```js
-const keyv = new Keyv();
-keyv.serialize = undefined;
-keyv.deserialize = undefined;
+import Keyv from 'keyv';
+import { KeyvMsgpackrSerializer } from '@keyv/serialize-msgpackr';
+
+const keyv = new Keyv({ serialization: new KeyvMsgpackrSerializer() });
 ```
 
+## Custom Serializers
+
+You can provide your own serializer by implementing the `KeyvSerializationAdapter` interface with `stringify` and `parse` methods:
+
+```typescript
+interface KeyvSerializationAdapter {
+  stringify: (object: unknown) => string | Promise<string>;
+  parse: <T>(data: string) => T | Promise<T>;
+}
+```
+
+## Disabling Serialization
+
+You can disable serialization entirely by passing `false`. This stores data as raw objects, which works for in-memory `Map` storage where string conversion is not needed:
+
+```js
+const keyv = new Keyv({ serialization: false });
+```
+
+## Pipeline
+
+When serialization and/or compression are configured, Keyv applies them in this order:
+
+**On set:** serialize (optional) → compress (optional) → store
+
+**On get:** store → decompress (optional) → parse (optional) → value
+
+If compression is configured without a serializer, Keyv will use `JSON.stringify`/`JSON.parse` as a minimum fallback since compression adapters require string input.
+
 # Official Storage Adapters
 
 The official storage adapters are covered by [over 150 integration tests](https://github.com/jaredwray/keyv/actions/workflows/tests.yaml) to guarantee consistent behaviour. They are lightweight, efficient wrappers over the DB clients making use of indexes and native TTLs where available.
 
 Database | Adapter | Native TTL
 ---|---|---
-Redis | [@keyv/redis](https://github.com/jaredwray/keyv/tree/master/storage/redis) | Yes
-Valkey | [@keyv/valkey](https://github.com/jaredwray/keyv/tree/master/storage/valkey) | Yes
-MongoDB | [@keyv/mongo](https://github.com/jaredwray/keyv/tree/master/storage/mongo) | Yes
-SQLite | [@keyv/sqlite](https://github.com/jaredwray/keyv/tree/master/storage/sqlite) | No
-PostgreSQL | [@keyv/postgres](https://github.com/jaredwray/keyv/tree/master/storage/postgres) | No
-MySQL | [@keyv/mysql](https://github.com/jaredwray/keyv/tree/master/storage/mysql) | No
-Etcd | [@keyv/etcd](https://github.com/jaredwray/keyv/tree/master/storage/etcd) | Yes
-Memcache | [@keyv/memcache](https://github.com/jaredwray/keyv/tree/master/storage/memcache) | Yes
-DynamoDB | [@keyv/dynamo](https://github.com/jaredwray/keyv/tree/master/storage/dynamo) | Yes
+Redis | [@keyv/redis](https://github.com/jaredwray/keyv/tree/main/storage/redis) | Yes
+Valkey | [@keyv/valkey](https://github.com/jaredwray/keyv/tree/main/storage/valkey) | Yes
+MongoDB | [@keyv/mongo](https://github.com/jaredwray/keyv/tree/main/storage/mongo) | Yes
+SQLite | [@keyv/sqlite](https://github.com/jaredwray/keyv/tree/main/storage/sqlite) | No
+PostgreSQL | [@keyv/postgres](https://github.com/jaredwray/keyv/tree/main/storage/postgres) | No
+MySQL | [@keyv/mysql](https://github.com/jaredwray/keyv/tree/main/storage/mysql) | No
+Etcd | [@keyv/etcd](https://github.com/jaredwray/keyv/tree/main/storage/etcd) | Yes
+Memcache | [@keyv/memcache](https://github.com/jaredwray/keyv/tree/main/storage/memcache) | Yes
+DynamoDB | [@keyv/dynamo](https://github.com/jaredwray/keyv/tree/main/storage/dynamo) | Yes
 
 # Third-party Storage Adapters
 
@@ -411,7 +463,7 @@ await keyv.delete('user:1');
 await keyv.clear();
 ```
 
-For more details about BigMap, see the [@keyv/bigmap documentation](https://github.com/jaredwray/keyv/tree/main/storage/bigmap).
+For more details about BigMap, see the [@keyv/bigmap documentation](https://github.com/jaredwray/keyv/tree/main/core/bigmap).
 
 # Compression
 
@@ -443,26 +495,145 @@ const keyv = new Keyv({ compression: keyvLz4 });
 
 You can also pass a custom compression function to the `compression` option. Following the pattern of the official compression adapters.
 
-## Want to build your own CompressionAdapter? 
+## Want to build your own KeyvCompressionAdapter?
 
 Great! Keyv is designed to be easily extended. You can build your own compression adapter by following the pattern of the official compression adapters based on this interface:
 
 ```typescript
-interface CompressionAdapter {
-	async compress(value: any, options?: any);
-	async decompress(value: any, options?: any);
-	async serialize(value: any);
-	async deserialize(value: any);
+interface KeyvCompressionAdapter {
+	compress(value: any, options?: any): Promise<any>;
+	decompress(value: any, options?: any): Promise<any>;
 }
 ```
 
 In addition to the interface, you can test it with our compression test suite using @keyv/test-suite:
 
 ```js
-import { keyvCompresstionTests } from '@keyv/test-suite';
+import { keyvCompressionTests } from '@keyv/test-suite';
 import KeyvGzip from '@keyv/compress-gzip';
 
-keyvCompresstionTests(test, new KeyvGzip());
+keyvCompressionTests(test, new KeyvGzip());
+```
+
+# Encryption
+
+Keyv provides a `KeyvEncryptionAdapter` interface for encryption support. This interface is available for custom implementations but is not yet wired into the core pipeline.
+
+```typescript
+interface KeyvEncryptionAdapter {
+  encrypt: (data: string) => string | Promise<string>;
+  decrypt: (data: string) => string | Promise<string>;
+}
+```
+
+# Capability Detection
+
+Keyv exports helper functions to check whether an object implements the expected interface for a Keyv instance, storage adapter, compression adapter, serialization adapter, or encryption adapter. Each function returns an object with boolean flags for every capability, plus a top-level boolean indicating whether the object fully satisfies the interface.
+
+```ts
+import {
+  detectKeyv,
+  detectKeyvStorage,
+  detectKeyvCompression,
+  detectKeyvSerialization,
+  detectKeyvEncryption,
+  detectCapabilities,
+} from 'keyv';
+```
+
+## detectKeyv(obj)
+
+Returns a `KeyvCapability` with a boolean for each Keyv method/property. The `keyv` flag is `true` only when **all** capabilities are present.
+
+```ts
+import Keyv, { detectKeyv } from 'keyv';
+
+detectKeyv(new Keyv());
+// { keyv: true, get: true, set: true, delete: true, clear: true, has: true,
+//   getMany: true, setMany: true, deleteMany: true, hasMany: true,
+//   disconnect: true, getRaw: true, getManyRaw: true, setRaw: true,
+//   setManyRaw: true, hooks: true, stats: true, iterator: true }
+
+detectKeyv(new Map());
+// { keyv: false, get: true, set: true, ... }
+```
+
+## detectKeyvStorage(obj)
+
+Returns a `KeyvStorageCapability`. The `keyvStorage` flag is `true` when the object has `get`, `set`, `delete`, `clear`, `has`, `setMany`, `deleteMany`, and `hasMany`.
+
+The result also includes:
+- **`mapLike`** — `true` when the object has synchronous `get`, `set`, `delete`, `has`, `entries`, and `keys` methods (i.e. it behaves like a `Map`)
+- **`methodTypes`** — a record mapping each method name to `"sync"`, `"async"`, or `"none"` (not present)
+
+```ts
+import { detectKeyvStorage } from 'keyv';
+
+// Map-like object
+const result = detectKeyvStorage(new Map());
+result.mapLike; // true
+result.methodTypes.get; // "sync"
+result.methodTypes.set; // "sync"
+
+// Async storage adapter
+const adapter = {
+  get: async () => {}, set: async () => {}, delete: async () => {},
+  clear: async () => {}, has: async () => {}, setMany: async () => {},
+  deleteMany: async () => {}, hasMany: async () => {},
+};
+const adapterResult = detectKeyvStorage(adapter);
+adapterResult.keyvStorage; // true
+adapterResult.mapLike; // false
+adapterResult.methodTypes.get; // "async"
+```
+
+## detectKeyvCompression(obj)
+
+Returns a `KeyvCompressionCapability`. The `keyvCompression` flag is `true` when both `compress` and `decompress` methods are present.
+
+```ts
+import { detectKeyvCompression } from 'keyv';
+
+detectKeyvCompression({ compress: (d) => d, decompress: (d) => d });
+// { keyvCompression: true, compress: true, decompress: true }
+```
+
+## detectKeyvSerialization(obj)
+
+Returns a `KeyvSerializationCapability`. The `keyvSerialization` flag is `true` when both `stringify` and `parse` methods are present.
+
+```ts
+import { detectKeyvSerialization } from 'keyv';
+
+detectKeyvSerialization(JSON);
+// { keyvSerialization: true, stringify: true, parse: true }
+```
+
+## detectKeyvEncryption(obj)
+
+Returns a `KeyvEncryptionCapability`. The `keyvEncryption` flag is `true` when both `encrypt` and `decrypt` methods are present.
+
+```ts
+import { detectKeyvEncryption } from 'keyv';
+
+detectKeyvEncryption({ encrypt: (d) => d, decrypt: (d) => d });
+// { keyvEncryption: true, encrypt: true, decrypt: true }
+```
+
+## detectCapabilities(obj, spec)
+
+A generic helper for building your own capability checks. Accepts a `CapabilitySpec` describing which methods and properties to look for, which are required, and the name of the composite boolean key.
+
+```ts
+import { detectCapabilities } from 'keyv';
+
+const result = detectCapabilities(myObject, {
+  methods: ['read', 'write'],
+  properties: ['name'],
+  requiredKeys: ['read', 'write', 'name'],
+  compositeKey: 'isValid',
+});
+// { isValid: true/false, read: true/false, write: true/false, name: true/false }
 ```
 
 # API
@@ -478,16 +649,14 @@ The Keyv instance is also an `EventEmitter` that will emit an `'error'` event if
 Type: `KeyvStorageAdapter`<br />
 Default: `undefined`
 
-The connection string URI.
-
-Merged into the options object as options.uri.
+The storage adapter instance to be used by Keyv.
 
 ## .namespace
 
 Type: `String`
-Default: `'keyv'`
+Default: `undefined`
 
-This is the namespace for the current instance. When you set it it will set it also on the storage adapter. This is the preferred way to set the namespace over `.opts.namespace`.
+This is the namespace for the current instance. When you set it it will set it also on the storage adapter.
 
 ## options
 
@@ -498,7 +667,7 @@ The options object is also passed through to the storage adapter. Check your sto
 ## options.namespace
 
 Type: `String`<br />
-Default: `'keyv'`
+Default: `undefined`
 
 Namespace for the current instance.
 
@@ -511,24 +680,17 @@ Default TTL. Can be overridden by specififying a TTL on `.set()`.
 
 ## options.compression
 
-Type: `@keyv/compress-<compression_package_name>`<br />
+Type: `KeyvCompressionAdapter`<br />
 Default: `undefined`
 
 Compression package to use. See [Compression](#compression) for more details.
 
-## options.serialize
-
-Type: `Function`<br />
-Default: `JSON.stringify`
+## options.serialization
 
-A custom serialization function.
+Type: `KeyvSerializationAdapter | false`<br />
+Default: `KeyvJsonSerializer` (built-in)
 
-## options.deserialize
-
-Type: `Function`<br />
-Default: `JSON.parse`
-
-A custom deserialization function.
+A serialization object with `stringify` and `parse` methods. Set to `false` to disable serialization and store raw objects. See [Serialization](#serialization) for more details.
 
 ## options.store
 
@@ -551,7 +713,7 @@ Returns a promise which resolves to `true`.
 
 ## .setMany(entries)
 
-Set multiple values using KeyvEntrys `{ key: string, value: any, ttl?: number }`.
+Set multiple values using `KeyvEntry<Value>` objects (`{ key: string, value: Value, ttl?: number }`). The `Value` type is inferred from the entries provided.
 
 ## .get(key, [options])
 
@@ -561,24 +723,50 @@ Returns a promise which resolves to the retrieved value.
 
 Returns a promise which resolves to an array of retrieved values.
 
-### options.raw - (Will be deprecated in v6)
+## .getRaw(key)
 
-Type: `Boolean`<br />
-Default: `false`
+Returns a promise which resolves to the raw stored data for the key or `undefined` if the key does not exist or is expired.
 
-If set to true the raw DB object Keyv stores internally will be returned instead of just the value.
+## .getManyRaw(keys)
 
-This contains the TTL timestamp.
+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.
 
-NOTE: This option will be deprecated in v6 and replaced with `.getRaw()` and `.getManyRaw()` methods.
+## .setRaw(key, value)
 
-## .getRaw(key)
+Sets a raw value in the store without wrapping. This is the write-side counterpart to `.getRaw()`. The caller provides the `KeyvValue` envelope directly (`{ value, expires? }`) instead of having Keyv wrap it. The envelope is still serialized before storing so that all read paths (`get()`, `getRaw()`, `has()`, `getManyRaw()`) work consistently. If you need TTL-based expiration, set `expires` on the value directly (e.g. `{ value: 'bar', expires: Date.now() + 60000 }`). The store-level TTL is derived automatically from `value.expires`.
 
-Returns a promise which resolves to the raw stored data for the key or `undefined` if the key does not exist or is expired.
+Returns a promise which resolves to `true`.
 
-## .getManyRaw(keys)
+```js
+const keyv = new Keyv();
 
-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.
+// Set a raw value with expiration
+await keyv.setRaw('foo', { value: 'bar', expires: Date.now() + 60000 });
+
+// Set a raw value without expiration
+await keyv.setRaw('foo', { value: 'bar' });
+
+// Round-trip: get raw, modify, set raw
+const raw = await keyv.getRaw('foo');
+if (raw) {
+  raw.value = 'updated';
+  await keyv.setRaw('foo', raw);
+}
+```
+
+## .setManyRaw(entries)
+
+Sets many raw values in the store without wrapping. Each entry should have a `key` and a `value` (`KeyvValue` envelope). Like `setRaw()`, the envelopes are serialized before storing and the store-level TTL is derived from each entry's `value.expires`.
+
+Returns a promise which resolves to an array of booleans.
+
+```js
+const keyv = new Keyv();
+await keyv.setManyRaw([
+  { key: 'foo', value: { value: 'bar' } },
+  { key: 'baz', value: { value: 'qux', expires: Date.now() + 60000 } },
+]);
+```
 
 ## .delete(key)
 
@@ -588,7 +776,7 @@ Returns a promise which resolves to `true` if the key existed, `false` if not.
 
 ## .deleteMany(keys)
 Deletes multiple entries.
-Returns a promise which resolves to an array of booleans indicating if the key existed or not.
+Returns a promise which resolves to `true` if all keys were deleted successfully, `false` otherwise.
 
 ## .clear()
 
@@ -596,19 +784,56 @@ Delete all entries in the current namespace.
 
 Returns a promise which is resolved when the entries have been cleared.
 
+## .has(key)
+
+Check if a key exists in the store.
+
+Returns a promise which resolves to `true` if the key exists, `false` if not.
+
+```js
+await keyv.set('foo', 'bar');
+await keyv.has('foo'); // true
+await keyv.has('unknown'); // false
+```
+
+## .hasMany(keys)
+
+Check if multiple keys exist in the store.
+
+Returns a promise which resolves to an array of booleans indicating if each key exists.
+
+```js
+await keyv.set('foo', 'bar');
+await keyv.hasMany(['foo', 'unknown']); // [true, false]
+```
+
+## .disconnect()
+
+Disconnect from the storage adapter. Emits a `'disconnect'` event.
+
+Returns a promise which is resolved when the connection has been closed.
+
+```js
+await keyv.disconnect();
+```
+
 ## .iterator()
 
-Iterate over all entries of the current namespace.
+Iterate over all key-value pairs in the store. Automatically deserializes values, filters out expired entries, and deletes them.
 
-Returns a iterable that can be iterated by for-of loops. For example:
+Returns an async generator that yields `[key, value]` pairs. Use with `for await...of`:
 
 ```js
-// please note that the "await" keyword should be used here
-for await (const [key, value] of this.keyv.iterator()) {
+for await (const [key, value] of keyv.iterator()) {
   console.log(key, value);
-};
+}
 ```
 
+The iterator works with any storage backend:
+- **Map stores**: iterates using the built-in `Symbol.iterator`
+- **Storage adapters**: delegates to the adapter's `iterator()` method (e.g., Redis SCAN, SQL cursor)
+- **Unsupported stores**: emits an `error` event if the store does not support iteration
+
 # API - Properties
 
 ## .namespace
@@ -626,7 +851,7 @@ here is an example of setting the namespace to `undefined`:
 
 ```js
 const keyv = new Keyv();
-console.log(keyv.namespace); // 'keyv' which is default
+console.log(keyv.namespace); // undefined which is default
 keyv.namespace = undefined;
 console.log(keyv.namespace); // undefined
 ```
@@ -660,40 +885,26 @@ keyv.store = new KeyvSqlite('sqlite://path/to/database.sqlite');
 console.log(keyv.store instanceof KeyvSqlite); // true
 ```
 
-## .serialize
-
-Type: `Function`<br />
-Default: `JSON.stringify`
-
-A custom serialization function used for any value. 
-
-```js
-const keyv = new Keyv();
-console.log(keyv.serialize); // JSON.stringify
-keyv.serialize = value => value.toString();
-console.log(keyv.serialize); // value => value.toString()
-```
-
-## .deserialize
+## .serialization
 
-Type: `Function`<br />
-Default: `JSON.parse`
+Type: `KeyvSerializationAdapter | false | undefined`<br />
+Default: `KeyvJsonSerializer` (built-in)
 
-A custom deserialization function used for any value.
+The serialization object used for storing and retrieving values. Set to `false` or `undefined` to disable serialization and use raw object pass-through. See [Serialization](#serialization) for more details.
 
 ```js
 const keyv = new Keyv();
-console.log(keyv.deserialize); // JSON.parse
-keyv.deserialize = value => parseInt(value);
-console.log(keyv.deserialize); // value => parseInt(value)
+console.log(keyv.serialization); // KeyvJsonSerializer (default)
+keyv.serialization = false; // disable serialization
+console.log(keyv.serialization); // undefined
 ```
 
 ## .compression
 
-Type: `CompressionAdapter`<br />
+Type: `KeyvCompressionAdapter`<br />
 Default: `undefined`
 
-this is the compression package to use. See [Compression](#compression) for more details. If it is undefined it will not compress (default).
+This is the compression package to use. See [Compression](#compression) for more details. If it is undefined it will not compress (default).
 
 ```js
 import KeyvGzip from '@keyv/compress-gzip';
@@ -734,6 +945,20 @@ await keyv.get('foo'); // 'bar'
 await keyv.clear();
 ```
 
+## .emitErrors
+
+Type: `Boolean`<br />
+Default: `true`
+
+If set to `true`, Keyv will emit an `'error'` event when an error occurs. Set to `false` to suppress error events.
+
+```js
+const keyv = new Keyv({ emitErrors: false });
+console.log(keyv.emitErrors); // false
+keyv.emitErrors = true;
+console.log(keyv.emitErrors); // true
+```
+
 ## .throwOnErrors
 
 Type: `Boolean`<br />
@@ -763,10 +988,10 @@ 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`
+Type: `KeyvStats`<br />
+Default: `KeyvStats` 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.
+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. It also maintains LRU-bounded per-key frequency maps for each event type, allowing you to see which keys are accessed most.
 
 ### Enabling Stats:
 ```js
@@ -775,12 +1000,21 @@ console.log(keyv.stats.enabled); // true
 ```
 
 ### Available Statistics:
+
+**Aggregate counters:**
 - `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
 
+**Per-key LRU frequency maps** (each capped at `maxEntries`, default 1000):
+- `hitKeys`: `Map<string, number>` — key to hit count
+- `missKeys`: `Map<string, number>` — key to miss count
+- `setKeys`: `Map<string, number>` — key to set count
+- `deleteKeys`: `Map<string, number>` — key to delete count
+- `errorKeys`: `Map<string, number>` — key to error count
+
 ### Accessing Stats:
 ```js
 const keyv = new Keyv({ stats: true });
@@ -794,23 +1028,104 @@ console.log(keyv.stats.hits);    // 1
 console.log(keyv.stats.misses);  // 1
 console.log(keyv.stats.sets);    // 1
 console.log(keyv.stats.deletes); // 1
+
+// Per-key frequency maps
+console.log(keyv.stats.hitKeys.get('foo'));          // 1
+console.log(keyv.stats.missKeys.get('nonexistent')); // 1
 ```
 
 ### Resetting Stats:
 ```js
 keyv.stats.reset();
 console.log(keyv.stats.hits); // 0
+console.log(keyv.stats.hitKeys.size); // 0
 ```
 
 ### Manual Control:
-You can also manually enable/disable stats tracking at runtime:
+You can also manually enable/disable stats tracking at runtime. Disabling stats will automatically unsubscribe from events:
 ```js
 const keyv = new Keyv({ stats: false });
 keyv.stats.enabled = true; // Enable stats tracking
 // ... perform operations ...
-keyv.stats.enabled = false; // Disable stats tracking
+keyv.stats.enabled = false; // Disable stats tracking and unsubscribe
 ```
 
+### Standalone Usage:
+You can create a `KeyvStats` instance independently and subscribe it to a Keyv instance:
+```js
+import { KeyvStats } from 'keyv';
+
+const stats = new KeyvStats({ enabled: true, maxEntries: 500, emitter: keyv });
+```
+
+## .sanitize
+Type: `boolean | KeyvSanitizeOptions`<br />
+Default: `false`
+
+Detects and strips dangerous patterns from keys and namespaces to protect against SQL injection, MongoDB operator injection, path traversal, and control character attacks. Harmless characters like quotes, slashes, and dollar signs pass through unchanged — only dangerous *patterns* are stripped.
+
+Results are cached in an LRU cache (10,000 entries) for fast repeated lookups.
+
+### Pattern Categories
+
+| Category | Patterns Stripped | Purpose |
+|----------|------------------|---------|
+| `sql` | `;` `--` `/*` | Prevents SQL injection |
+| `mongo` | leading `$`, `{$` sequences | Prevents MongoDB operator injection |
+| `escape` | `\0` `\r` `\n` | Strips null bytes, CRLF injection |
+| `path` | `../` `..\` | Prevents path traversal |
+
+### Targets
+
+| Target | Default | Description |
+|--------|---------|-------------|
+| `keys` | `true` (when enabled) | Sanitize keys on all operations |
+| `namespace` | `true` (when enabled) | Sanitize namespace on construction and setter |
+
+### Usage
+
+Enable all sanitization:
+```js
+const keyv = new Keyv({ sanitize: true });
+await keyv.set("test; DROP TABLE", "value");
+// Key is stored as "test DROP TABLE"
+
+// Harmless characters pass through
+await keyv.set("user's-data", "value");
+// Key is stored as "user's-data" (unchanged)
+```
+
+Disable all sanitization (default):
+```js
+const keyv = new Keyv({ sanitize: false });
+```
+
+Granular control per target and category:
+```js
+const keyv = new Keyv({
+  sanitize: {
+    keys: { sql: true, mongo: false },     // only SQL patterns on keys
+    namespace: { path: true, sql: false },  // only path patterns on namespace
+  }
+});
+```
+
+Disable namespace sanitization only:
+```js
+const keyv = new Keyv({
+  sanitize: { keys: true, namespace: false }
+});
+```
+
+Change at runtime:
+```js
+keyv.sanitize = false; // disable
+keyv.sanitize = true;  // enable all
+keyv.sanitize = { keys: { sql: true, mongo: false } }; // granular
+```
+
+Sanitization is applied to all key-accepting methods: `get`, `set`, `delete`, `has`, `getMany`, `setMany`, `deleteMany`, `hasMany`, `getRaw`, `getManyRaw`, `setRaw`, and `setManyRaw`. Namespace sanitization is applied at construction and when the `namespace` setter is used.
+
 # Bun Support
 
 We make a best effort to support [Bun](https://bun.sh/) as a runtime. Our default and primary target is Node.js, but we run tests against Bun to ensure compatibility. If you encounter any issues while using Keyv with Bun, please report them at our [GitHub issues](https://github.com/jaredwray/keyv/issues).