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

package/LICENSE

@@ -1,7 +1,7 @@
 MIT License
 
 Copyright (c) 2017-2021 Luke Childs
-Copyright (c) 2021-2022 Jared Wray
+Copyright (c) 2021-2026 Jared Wray
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

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)
@@ -37,6 +38,7 @@ There are a few existing modules similar to Keyv, however Keyv is different beca
 - [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)
@@ -48,6 +50,7 @@ There are a few existing modules similar to Keyv, however Keyv is different beca
   - [.emitErrors](#emiterrors)
   - [.throwOnErrors](#throwonerrors)
   - [.stats](#stats)
+  - [.sanitize](#sanitize)
   - [Keyv Instance](#keyv-instance)
 	- [.set(key, value, [ttl])](#setkey-value-ttl)
 	- [.setMany(entries)](#setmanyentries)
@@ -55,7 +58,7 @@ 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, [ttl])](#setrawkey-value-ttl)
+  - [.setRaw(key, value)](#setrawkey-value)
   - [.setManyRaw(entries)](#setmanyrawentries)
 	- [.delete(key)](#deletekey)
 	- [.deleteMany(keys)](#deletemanykeys)
@@ -302,37 +305,42 @@ In `PRE_DELETE` and `POST_DELETE` hooks, the value could be a single item or an
 
 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.
 
-## Custom Serializers
+## Official Serializers
 
-You can provide your own serializer by implementing the `KeyvSerializationAdapter` interface:
+In addition to the built-in serializer, Keyv offers two official serialization packages:
 
-```typescript
-interface KeyvSerializationAdapter {
-  stringify: (object: unknown) => string | Promise<string>;
-  parse: <T>(data: string) => T | Promise<T>;
-}
-```
+### SuperJSON
 
-For example, using the built-in `JSON` object:
+[`@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({
-  serialization: { stringify: JSON.stringify, parse: 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 });
 ```
 
-Or a custom async serializer:
+### MessagePack (msgpackr)
+
+[`@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({
-  serialization: {
-    stringify: async (value) => JSON.stringify(value),
-    parse: async (data) => JSON.parse(data),
-  },
-});
+import Keyv from 'keyv';
+import { KeyvMsgpackrSerializer } from '@keyv/serialize-msgpackr';
+
+const keyv = new Keyv({ serialization: new KeyvMsgpackrSerializer() });
 ```
 
-**Warning:** Using custom serializers means you lose any guarantee of data consistency. You should do extensive testing with your serialization functions and chosen storage engine.
+## 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
 
@@ -358,15 +366,15 @@ The official storage adapters are covered by [over 150 integration tests](https:
 
 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
 
@@ -501,10 +509,10 @@ interface KeyvCompressionAdapter {
 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
@@ -518,6 +526,116 @@ interface KeyvEncryptionAdapter {
 }
 ```
 
+# 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
 
 ## new Keyv([storage-adapter], [options]) or new Keyv([options])
@@ -536,9 +654,9 @@ 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
 
@@ -549,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.
 
@@ -595,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])
 
@@ -613,30 +731,32 @@ Returns a promise which resolves to the raw stored data for the key or `undefine
 
 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.
 
-## .setRaw(key, value, [ttl])
+## .setRaw(key, value)
 
-Sets a raw value in the store without wrapping. This is the write-side counterpart to `.getRaw()`. The caller provides the `DeserializedData` 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 `expires` is not set in the value and `ttl` is provided, `expires` will be computed from `ttl`.
+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 `true`.
 
 ```js
 const keyv = new Keyv();
 
-// Set a raw value directly
+// 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');
-raw.value = 'updated';
-await keyv.setRaw('foo', raw);
-
-// TTL computes expires automatically if not set
-await keyv.setRaw('foo', { value: 'bar' }, 60000);
+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`, a `value` (`DeserializedData` envelope), and an optional `ttl`. Like `setRaw()`, the envelopes are serialized before storing.
+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.
 
@@ -699,17 +819,21 @@ 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
@@ -727,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
 ```
@@ -864,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
@@ -876,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 });
@@ -895,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).