keyv-wise-json

A Keyv store implementation using WiseJSON DB as the backend storage.

Features

• Multi-process safe - Uses file locking (WAL + proper-lockfile) to prevent data corruption
• Crash-proof - WAL (Write-Ahead Logging) guarantees data integrity and recovery after crashes
• ACID transactions - Ensures data consistency
• File-based storage - Persistent key-value storage with no separate database server needed
• Namespace support - Organize your data with namespaces
• TTL support - Set time-to-live for automatic key expiration
• TypeScript - Fully typed with TypeScript support

Installation

bun install keyv-wise-json wise-json-db

Or with npm:

npm install keyv-wise-json wise-json-db

Usage

Basic Example

import Keyv from "keyv";
import KeyvWiseJsonStore from "keyv-wise-json";

// Create a store with file-based persistence
const store = new KeyvWiseJsonStore("path/to/db");

const keyv = new Keyv({ store });

// Set a value
await keyv.set("foo", "bar");

// Get a value
const value = await keyv.get("foo"); // "bar"

// Delete a value
await keyv.delete("foo");

// Clear all values
await keyv.clear();

With Namespace

const store = new KeyvWiseJsonStore("path/to/db", { namespace: "myapp" });
const keyv = new Keyv({ store });

await keyv.set("user:1", { name: "Alice" });
// Stored with key: "myapp:user:1"

With TTL (Time-To-Live)

const keyv = new Keyv({ store });

// Set a value that expires in 1 second
await keyv.set("temp", "value", 1000);

// Wait for expiration
await new Promise((resolve) => setTimeout(resolve, 1100));

const value = await keyv.get("temp"); // undefined

API

new KeyvWiseJsonStore(dbPath?, options?)

Creates a new WiseJSON store instance.

Parameters

• dbPath (string, optional) - Path to the database directory. Defaults to "keyv-wise-json-data"
• options (object, optional):
  • namespace (string) - Prefix for all keys
  • collectionName (string) - WiseJSON collection name. Defaults to "keyv"

Store Methods

Implements the Keyv Store Adapter interface:

• get(key) - Get a value by key
• getMany(keys) - Get multiple values by keys
• set(key, value, ttl?) - Set a value with optional TTL in milliseconds
• delete(key) - Delete a value by key
• clear() - Clear all values (respects namespace)
• iterator(namespace?) - Async iterator for all key-value pairs
• close() - Close the database connection

Iteration

const store = new KeyvWiseJsonStore("path/to/db");

await store.set("user:1", { name: "Alice" });
await store.set("user:2", { name: "Bob" });

for await (const [key, value] of store.iterator()) {
  console.log(key, value);
}

Why WiseJSON DB?

WiseJSON DB is a crash-proof embedded JSON database that:

• Uses WAL (Write-Ahead Logging) for data integrity
• Supports multi-process access via file locking
• ACID-compliant transactions
• No separate database server needed
• Lightweight with minimal dependencies

Perfect for:

• Multi-process applications that share a cache
• Crash-proof persistent storage
• Serverless environments
• Configuration and cache storage

Development

Built with Bun:

# Install dependencies
bun install

# Run tests
bun test

# Build
bun run build

See Also

Other Keyv storage adapters by the same author:

• keyv-nedb-store — NeDB storage adapter
• keyv-github — GitHub repository adapter
• keyv-sqlite — SQLite storage adapter
• keyv-dir-store — file-per-key directory adapter
• keyv-cache-proxy — transparent caching proxy
• keyv-nest — hierarchical multi-layer caching adapter

License

MIT

Related

• Keyv - Simple key-value storage with support for multiple backends
• WiseJSON DB - Crash-proof embedded JSON database for Node.js