Encode and Decode

Keyv stores an envelope { value, expires? }, not the raw value. encode() turns that envelope into what the adapter persists. decode() turns the adapter's bytes back into the envelope.

Table of Contents

• Pipeline
• Built-in JSON serializer
• Official serializers
• Custom serializer
• Disabling serialization
• Compression and encryption
• decodeWithExpire

Pipeline

On set: serialize → compress (optional) → encrypt (optional) → store

On get: store → decrypt (optional) → decompress (optional) → parse → value

Compression and encryption operate on the serialized string. They only run when a serializer is configured. The built-in KeyvJsonSerializer is on by default, so this works out of the box.

If you set serialization: false, values go to the store as-is and compression is skipped. With an encryption adapter set, writes fail with an error instead, so nothing is stored unencrypted.

const packed = await keyv.encode({ value: { n: 1 }, expires: Date.now() + 1000 });
const envelope = await keyv.decode(packed);
// { value: { n: 1 }, expires: ... }

decode returns undefined for null / undefined input, or if decrypt/decompress/parse throws (the error is emitted as 'error').

Built-in JSON serializer

KeyvJsonSerializer is the default. It uses JSON.stringify / JSON.parse with extra tags:

• Buffer / Uint8Array → :base64:...
• BigInt → :bigint:...
• Strings that already start with : are escaped so they round-trip

In browsers without Buffer, it uses btoa / atob.

import Keyv, { KeyvJsonSerializer, jsonSerializer } from "keyv";

const keyv = new Keyv(); // already using KeyvJsonSerializer
keyv.serialization = jsonSerializer; // shared instance

Official serializers

import { superJsonSerializer } from "@keyv/serialize-superjson";
import { msgpackrSerializer } from "@keyv/serialize-msgpackr";

const withDates = new Keyv({ serialization: superJsonSerializer });
const compact = new Keyv({ serialization: msgpackrSerializer });

Custom serializer

interface KeyvSerializationAdapter {
	stringify: (object: unknown) => string | Promise<string>;
	parse: <T>(data: string) => T | Promise<T>;
}

const serializer = {
	stringify: (value) => JSON.stringify(value),
	parse: (data) => JSON.parse(data),
};
const keyv = new Keyv({ serialization: serializer });

Disabling serialization

Useful for an in-memory Map of objects when you do not need a string payload:

const keyv = new Keyv({ store: new Map(), serialization: false });

Do not disable serialization if you use compression, encryption, or a backend that only stores strings.

Compression and encryption

import KeyvGzip from "@keyv/compress-gzip";
import KeyvEncryptNode from "@keyv/encrypt-node";

const keyv = new Keyv({
	compression: new KeyvGzip(),
	encryption: new KeyvEncryptNode({ key: process.env.KEYV_SECRET }),
});

See Compression and Encryption.

decodeWithExpire

Internal helper used by get / has when checkExpired is on. It decodes each row and deletes keys whose expires is in the past. You can call it if you are reading raw adapter rows yourself.