keyv-file

library5.3.3jsnpmunverified

File storage adapter for Keyv, using JSON (or msgpack) to serialize data fast and small. Current stable version is 5.3.3, with regular releases. It provides persistent caching with efficient TTL handling via interval scans, batch write delays for performance, and direct usage patterns with field-based access. Compared to other Keyv storage adapters, keyv-file focuses on simplicity and local file persistence, making it suitable for small-scale caching needs where a database is overkill.

storage devops

npm install keyv-file

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KEYV-FILE

keyv-file

storagejavascriptv5.3.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

KeyvFile

✓ import { KeyvFile } from 'keyv-file'

✗ const KeyvFile = require('keyv-file')

ESM-only since v5; named export, not default.

keyv

✓ import Keyv from 'keyv'

✗ const { Keyv } = require('keyv')

Keyv has a default export; using named import incorrectly.

makeField

✓ import { makeField } from 'keyv-file'

✗ import makeField from 'keyv-file'

makeField is a named export, not default.

Initializes Keyv with a file store, sets and gets a value, demonstrating basic caching.

import Keyv from 'keyv'; import { KeyvFile } from 'keyv-file'; const keyv = new Keyv({ store: new KeyvFile({ filename: './cache.json', expiredCheckDelay: 24 * 3600 * 1000, writeDelay: 100 }) }); await keyv.set('foo', 'bar'); const value = await keyv.get('foo'); console.log(value); // 'bar'

Debug

Known issues

breakingVersion 5 dropped CommonJS support; imports must be ESM.

fix

Use import syntax instead of require().

affects: >=5.0.0

deprecatedThe encode/decode options default to JSON.stringify/parse; using msgpack is possible but not documented.

fix

Switch to JSON default or explicitly set encode/decode.

affects: <5.0.0

gotchaFile writes are batched with a delay (default 100ms); immediate reads after writes may not reflect data.

fix

Use await keyv.set() and ensure write delay elapses or flush manually.

affects: >=1.0.0

gotchaTTL expiry is checked periodically (default every 24h); expired data may persist temporarily.

fix

Set expiredCheckDelay lower for more frequent cleanup, or accept eventual cleanup.

affects: >=1.0.0

breakingIn v4, the constructor was named 'KeyvFile' but was a default export. In v5, it's a named export.

fix

Use { KeyvFile } instead of KeyvFile as default import.

affects: >=5.0.0

Errors

Common errors & fixes

TypeError: keyv_file_1.KeyvFile is not a constructor

Using require() on ESM-only package.

fix

Switch to import { KeyvFile } from 'keyv-file'.

Error: Cannot find module 'keyv'

keyv is a peer dependency not installed.

fix

Run npm install keyv.

TypeError: store.set is not a function

Store constructor called without 'new' or wrong import.

fix

Ensure you do new KeyvFile({...}) and import correctly.

SyntaxError: Unexpected token ':'

Using JSON5 syntax or invalid JSON in file.

fix

Ensure the file content is valid JSON.

Upgrade

Version history

5.3.3latest on npm

Audit

Dependencies

keyvrequiredPeer dependency required to use keyv-file as a store; must be installed alongside.

Agent activity

19 hits · last 30 days

node

Resources

githubhttps://github.com/zaaack/keyv-file ↗

packagekeyv-file ↗

homepagehttps://github.com/zaaack/keyv-file#readme ↗