keyv 6.0.0-alpha.2 → 6.0.0-alpha.3

package/README.md

@@ -19,7 +19,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,7 +32,7 @@ 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)
@@ -42,10 +42,11 @@ There are a few existing modules similar to Keyv, however Keyv is different beca
   - [.namespace](#namespace)
   - [.ttl](#ttl)
   - [.store](#store)
-  - [.serialize](#serialize)
-  - [.deserialize](#deserialize)
+  - [.serialization](#serialization-1)
   - [.compression](#compression)
   - [.useKeyPrefix](#usekeyprefix)
+  - [.emitErrors](#emiterrors)
+  - [.throwOnErrors](#throwonerrors)
   - [.stats](#stats)
   - [Keyv Instance](#keyv-instance)
 	- [.set(key, value, [ttl])](#setkey-value-ttl)
@@ -54,9 +55,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, [ttl])](#setrawkey-value-ttl)
+  - [.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 +225,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,26 +298,60 @@ 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.
+## Custom Serializers
+
+You can provide your own serializer by implementing the `KeyvSerializationAdapter` interface:
+
+```typescript
+interface KeyvSerializationAdapter {
+  stringify: (object: unknown) => string | Promise<string>;
+  parse: <T>(data: string) => T | Promise<T>;
+}
+```
+
+For example, using the built-in `JSON` object:
 
 ```js
-const keyv = new Keyv({ serialize: JSON.stringify, deserialize: JSON.parse });
+const keyv = new Keyv({
+  serialization: { stringify: JSON.stringify, parse: JSON.parse },
+});
+```
+
+Or a custom async serializer:
+
+```js
+const keyv = new Keyv({
+  serialization: {
+    stringify: async (value) => JSON.stringify(value),
+    parse: async (data) => JSON.parse(data),
+  },
+});
 ```
 
-**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.
+**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.
 
-If you do not want to use serialization you can set the `serialize` and `deserialize` functions to `undefined`. This will also turn off compression.
+## 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();
-keyv.serialize = undefined;
-keyv.deserialize = undefined;
+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.
@@ -411,7 +455,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,16 +487,14 @@ 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>;
 }
 ```
 
@@ -465,6 +507,17 @@ import KeyvGzip from '@keyv/compress-gzip';
 keyvCompresstionTests(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>;
+}
+```
+
 # API
 
 ## new Keyv([storage-adapter], [options]) or new Keyv([options])
@@ -478,9 +531,7 @@ 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
 
@@ -511,24 +562,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`
-
-A custom serialization function.
+## options.serialization
 
-## options.deserialize
+Type: `KeyvSerializationAdapter | false`<br />
+Default: `KeyvJsonSerializer` (built-in)
 
-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
 
@@ -561,24 +605,48 @@ 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, [ttl])
 
-## .getRaw(key)
+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`.
 
-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 directly
+await keyv.setRaw('foo', { value: 'bar', expires: Date.now() + 60000 });
+
+// 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);
+```
+
+## .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.
+
+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 +656,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,6 +664,39 @@ 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.
@@ -660,40 +761,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 +821,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 />