Hooks

Every Keyv operation fires a before:* hook, then the store call, then an after:* hook. Hooks can observe or mutate the payload (for example prefixing keys on BEFORE_SET).

Register handlers with onHook() or addHook() from Hookified. Import names from KeyvHooks.

import Keyv, { KeyvHooks } from "keyv";

const keyv = new Keyv();

keyv.onHook(KeyvHooks.BEFORE_SET, (data) => {
	console.log(`Setting ${data.key}`);
});

addHook(event, handler) is the same registration API used in the test suite.

Table of Contents

• Hook names (KeyvHooks)
• Mutating BEFORE_SET
• Hits and misses
• Delete hooks
• Deprecated PRE_* / POST_* names
• Hook errors

Hook names (KeyvHooks)

Mutating BEFORE_SET

The object passed to BEFORE_SET is { key, value, ttl }. Mutations are used for the write.

keyv.onHook(KeyvHooks.BEFORE_SET, (data) => {
	data.key = `prefix-${data.key}`;
	data.value = { wrapped: data.value };
});

Hits and misses

AFTER_GET and AFTER_GET_RAW run on both hits and misses. A miss (missing or expired) passes undefined as the value.

keyv.onHook(KeyvHooks.AFTER_GET, (data) => {
	if (data.value === undefined) {
		console.log("miss", data.key);
	} else {
		console.log("hit", data.key, data.value);
	}
});

Delete hooks

delete() accepts a single key or an array (which delegates to deleteMany). BEFORE_DELETE / AFTER_DELETE therefore see either a string or an array. Prefer BEFORE_DELETE_MANY / AFTER_DELETE_MANY for batch deletes. Keyv still fires the single-key delete hooks from deleteMany for backward compatibility.

Deprecated PRE_* / POST_* names

The v5 names (PRE_SET → "preSet", POST_GET → "postGet", …) still fire if anything is subscribed to them. Keyv emits deprecation warnings. Use BEFORE_* / AFTER_* going forward.

// works, but deprecated
keyv.addHook(KeyvHooks.PRE_SET, () => {});

Hook errors

throwOnHookError defaults to false. A throwing hook emits 'error' instead of failing the Keyv call. Set keyv.throwOnHookError = true if a hook failure should fail the operation.