Keyv Directory Store

High performance Filesystem Keyv Store, caches each key-value pair into a $key.json. and more! _.JSON, _.YAML, *.CSV is also avaliable.

This package provides a filesystem-based storage adapter for Keyv, storing each key-value pair in individual files with support for various formats.

Features

• ✅ Persistent storage using the filesystem
• ✅ Individual files per key-value pair
• ✅ String values only (use Keyv wrapper for object serialization)
• ✅ TTL (Time-To-Live) support using file modification times
• ✅ Full compatibility with Keyv API
• ✅ Customizable file naming and prefix/suffix
• ✅ Use with keyv-nest for memory caching layer

Installation

# Using npm
npm install keyv keyv-dir-store

# Using yarn
yarn add keyv keyv-dir-store

# Using pnpm
pnpm add keyv keyv-dir-store

# Using bun
bun add keyv keyv-dir-store

Usage Examples

Basic Usage

import Keyv from "keyv";
import { KeyvDirStore } from "keyv-dir-store";

// Default: Store each value with JSON
const keyv = new Keyv({
  store: new KeyvDirStore(".cache/kv"),
});

// Set a value (never expires)
await keyv.set("key1", "value1");

// Set a value with TTL (expires after 1 day)
await keyv.set("key2", "value2", 86400000);

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

// Check if a key exists
const exists = await keyv.has("key1");

// Delete a key
await keyv.delete("key1");

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

Format-Specific Examples

Store with JSON (using provided helper)

import Keyv from "keyv";
import { KeyvDirStore } from "keyv-dir-store";
import { KeyvDirStoreAsJSON } from "keyv-dir-store/KeyvDirStoreAsJSON";

const keyv = new Keyv({
  store: new KeyvDirStore(".cache/kv", { suffix: ".json" }),
  ...KeyvDirStoreAsJSON,
});

Store with YAML (using provided helper)

import Keyv from "keyv";
import { KeyvDirStore } from "keyv-dir-store";
import { KeyvDirStoreAsYaml } from "keyv-dir-store/KeyvDirStoreAsYaml";

const keyv = new Keyv({
  store: new KeyvDirStore(".cache/kv", { suffix: ".yaml" }),
  ...KeyvDirStoreAsYaml,
});

Store Object Lists with CSV

import Keyv from "keyv";
import { KeyvDirStore } from "keyv-dir-store";
import * as d3 from "d3";

const keyv = new Keyv({
  store: new KeyvDirStore(".cache/kv", { suffix: ".csv" }),
  serialize: ({ value }) => d3.csvFormat(value),
  deserialize: (str) => ({ value: d3.csvParse(str), expires: undefined }),
});

Store Object Lists with TSV

import Keyv from "keyv";
import { KeyvDirStore } from "keyv-dir-store";
import * as d3 from "d3";

const keyv = new Keyv({
  store: new KeyvDirStore(".cache/kv", { suffix: ".tsv" }),
  serialize: ({ value }) => d3.tsvFormat(value),
  deserialize: (str) => ({ value: d3.tsvParse(str), expires: undefined }),
});

API Reference

new KeyvDirStore(directory, options?)

Creates a new KeyvDirStore instance.

Parameters

• directory (string): The directory path where files will be stored
• options (object, optional):
  • filename (function, optional): Custom filename generator function
  • prefix (string, optional): Path prefix prepended to every key (e.g. 'data/'). Defaults to ''
  • suffix (string, optional): Path suffix appended to every key (e.g. '.json'). Defaults to ''

Example with Custom Options

import Keyv from "keyv";
import { KeyvDirStore } from "keyv-dir-store";

const keyv = new Keyv({
  store: new KeyvDirStore(".cache/kv", {
    // Custom file suffix/extension
    suffix: ".data",

    // Custom filename generator
    filename: (key) => `custom-prefix-${key}`,
  }),
});

Mirror KeyvGithub paths (for use with keyv-nest)

Use the same prefix/suffix as KeyvGithub with filename: (k) => k for raw paths:

import KeyvNest from "keyv-nest";
import { KeyvDirStore } from "keyv-dir-store";
import KeyvGithub from "keyv-github";

const prefix = "data/";
const suffix = ".json";

const store = KeyvNest(
  new KeyvDirStore("./cache", {
    prefix,
    suffix,
    filename: (k) => k,  // use key as-is, no hashing
  }),
  new KeyvGithub("owner/repo", { client, prefix, suffix })
);

// key "foo" -> ./cache/data/foo.json (local) and data/foo.json (GitHub)

How It Works

1. Each key-value pair is stored in a separate file on disk
2. The key is used to generate a filename (with sanitization)
3. Values must be strings (use Keyv wrapper for object serialization)
4. TTL information is stored in the file's modification time

Note: This store has no in-memory cache. Use keyv-nest to add a memory cache layer:

import KeyvNest from "keyv-nest";
const store = KeyvNest(new Map(), new KeyvDirStore("./cache"));

Warning: TTL is stored using file mtime, which may be modified by other programs (backup tools, sync services, file explorers, etc.). For reliable TTL behavior, use the standard Keyv wrapper which stores expiry in the serialized value itself:

// Keyv handles TTL internally - safe from mtime changes
const keyv = new Keyv({ store: new KeyvDirStore("./cache") });
await keyv.set("key", "value", 60000); // TTL stored in value, not mtime

See Also

Other Keyv storage adapters by the same author:

• keyv-github — GitHub repository adapter; each key is a file, commits are writes
• keyv-sqlite — SQLite storage adapter
• keyv-mongodb-store — MongoDB storage adapter
• keyv-nedb-store — NeDB embedded file-based adapter
• keyv-cache-proxy — transparent caching proxy that wraps any object
• keyv-nest — hierarchical multi-layer caching adapter

License

MIT © snomiao

Contributing

Contributions, issues, and feature requests are welcome! Feel free to check issues page.

Acknowledgements

This package is built on top of the excellent Keyv library.