keyv-dir-store 0.0.9 → 1.0.0

package/README.md

@@ -1,41 +1,217 @@
 # 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.
+High performance Filesystem Keyv Store, caches each key-value pair into a $key.json. and more! _.JSON, _.YAML, \*.CSV is also avaliable.
 
-## Usages
+[![npm version](https://badge.fury.io/js/keyv-dir-store.svg)](https://www.npmjs.com/package/keyv-dir-store)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+This package provides a filesystem-based storage adapter for [Keyv](https://github.com/jaredwray/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
+- ✅ Support customize serialize/deserialize, you can store your data into JSON, YAML, CSV, and TSV formats
+- ✅ TTL (Time-To-Live) support using file modification times
+- ✅ In-memory caching for improved performance
+- ✅ Full compatibility with Keyv API
+- ✅ Customizable file naming and extensions
+
+## Installation
+
+```bash
+# 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
 
 ```ts
-// Default: Store each value with JSON in format "{value: ..., expires: ...}"
-new Keyv({
-  store: new KeyvDirStore(".cache/kv")
+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"),
 });
 
-// Store each object list with CSV
-new Keyv({
-  store: new KeyvDirStore(".cache/kv", { ext: ".csv" }),
+// 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)
+
+```ts
+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)
+
+```ts
+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
+
+```ts
+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 each object list with TSV
-new Keyv({
-  store: new KeyvDirStore(".cache/kv", { ext: ".tsv" }),
+#### Store Object Lists with TSV
+
+```ts
+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 }),
 });
+```
 
-// Store each value with YAML
-new Keyv({
-  store: new KeyvDirStore(".cache/kv", { ext: ".json" }),
-  serialize: ({ value }) => yaml.stringify(value),
-  deserialize: (str) => ({ value: yaml.parse(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):
+  - `cache` (Map, optional): Custom cache Map to use
+  - `filename` (function, optional): Custom filename generator function
+  - `prefix` (string, optional): Path prefix prepended to every key (e.g. `'data/'`)
+  - `suffix` (string, optional): Path suffix appended to every key (default: `.json`)
 
-// Store each value with JSON
-new Keyv({
-  store: new KeyvDirStore(".cache/kv", { ext: ".json" }),
-  serialize: ({ value }) => JSON.stringify(value, null, 2),
-  deserialize: (str) => ({ value: JSON.parse(str), expires: undefined }),
+#### Example with Custom Options
+
+```ts
+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:
+
+```ts
+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. The value is serialized using the specified format
+4. TTL information is stored in the file's modification time
+5. An in-memory cache is used to improve performance
+
+> **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:
+> ```ts
+> // 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](https://github.com/snomiao/keyv-github) — GitHub repository adapter; each key is a file, commits are writes
+- [keyv-sqlite](https://github.com/snomiao/keyv-sqlite) — SQLite storage adapter
+- [keyv-mongodb-store](https://github.com/snomiao/keyv-mongodb-store) — MongoDB storage adapter
+- [keyv-nedb-store](https://github.com/snomiao/keyv-nedb-store) — NeDB embedded file-based adapter
+- [keyv-cache-proxy](https://github.com/snomiao/keyv-cache-proxy) — transparent caching proxy that wraps any object
+- [keyv-nest](https://github.com/snomiao/keyv-nest) — hierarchical multi-layer caching adapter
+
+## License
+
+MIT © [snomiao](https://github.com/snomiao)
+
+## Contributing
+
+Contributions, issues, and feature requests are welcome!
+Feel free to check [issues page](https://github.com/snomiao/keyv-dir-store/issues).
+
+## Acknowledgements
 
-```
+This package is built on top of the excellent [Keyv](https://github.com/jaredwray/keyv) library.

package/dist/index.js

@@ -4,15 +4,29 @@ var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
 var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
   for (let key of __getOwnPropNames(mod))
     if (!__hasOwnProp.call(to, key))
       __defProp(to, key, {
-        get: () => mod[key],
+        get: __accessProp.bind(mod, key),
         enumerable: true
       });
+  if (canCache)
+    cache.set(mod, to);
   return to;
 };
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
@@ -330,18 +344,22 @@ class KeyvDirStore {
   #cache;
   #ready;
   #filename;
-  ext = ".json";
+  opts = {};
+  namespace;
+  prefix;
+  suffix;
   constructor(dir, {
     cache = new Map,
     filename,
-    ext
+    prefix,
+    suffix
   } = {}) {
-    this.#ready = mkdir(dir, { recursive: true }).catch(() => {
-    });
+    this.#ready = mkdir(dir, { recursive: true }).catch(() => {});
     this.#cache = cache;
     this.#dir = dir;
     this.#filename = filename ?? this.#defaultFilename;
-    this.ext = ext ?? this.ext;
+    this.prefix = prefix ?? "";
+    this.suffix = suffix ?? ".json";
   }
   #defaultFilename(key) {
     const readableName = import_sanitize_filename.default(key).slice(0, 16);
@@ -350,7 +368,10 @@ class KeyvDirStore {
     return name;
   }
   #path(key) {
-    return path.join(this.#dir, import_sanitize_filename.default(this.#filename(key) + this.ext));
+    const filename = this.#filename(key);
+    const safeFilename = import_sanitize_filename.default(filename + this.suffix);
+    const relativePath = this.prefix + safeFilename;
+    return path.join(this.#dir, relativePath);
   }
   async get(key) {
     const memCached = this.#cache.get(key);
@@ -383,10 +404,10 @@ class KeyvDirStore {
     const expires = ttl ? Date.now() + ttl : 0;
     this.#cache.set(key, { value, expires });
     await this.#ready;
-    await mkdir(this.#dir, { recursive: true }).catch(() => {
-    });
-    await writeFile(this.#path(key), value);
-    await utimes(this.#path(key), new Date, new Date(expires ?? 0));
+    const filePath = this.#path(key);
+    await mkdir(path.dirname(filePath), { recursive: true }).catch(() => {});
+    await writeFile(filePath, value);
+    await utimes(filePath, new Date, new Date(expires ?? 0));
     return true;
   }
   async delete(key) {
@@ -408,6 +429,9 @@ class KeyvDirStore {
   static deserialize(str) {
     return { value: JSON.parse(str), expires: undefined };
   }
+  on(_event, _listener) {
+    return this;
+  }
 }
 export {
   KeyvDirStore

package/index.ts

@@ -1,4 +1,4 @@
-import type { DeserializedData, default as Keyv } from "keyv";
+import type { DeserializedData, KeyvStoreAdapter } from "keyv";
 import md5 from "md5";
 import { mkdir, readFile, rm, stat, utimes, writeFile } from "node:fs/promises";
 import path from "path";
@@ -8,9 +8,13 @@ type CacheMap<Value> = Map<string, DeserializedData<Value>>;
 /**
  * KeyvDirStore is a Keyv.Store<string> implementation that stores data in files.
  *
+ * **Warning**: TTL is stored in file mtime, which may be modified by other programs
+ * (backup tools, sync services, etc.). For reliable TTL, wrap this store with Keyv:
+ * `new Keyv({ store: new KeyvDirStore(...) })` - Keyv stores expiry in the value itself.
+ *
  * learn more [README](./README.md)
  *
- * @example
+ * @example Basic usage
  * const kv = new Keyv<number | string | { obj: boolean }>({
  *   store: new KeyvDirStore("cache/test"),
  *   deserialize: KeyvDirStore.deserialize,
@@ -21,13 +25,28 @@ type CacheMap<Value> = Map<string, DeserializedData<Value>>;
  * await kv.set("b", 1234); // never expired
  * expect(await kv.get("b")).toEqual(1234);
  *
+ * @example Mirror KeyvGithub paths (for use with keyv-nest)
+ * // Use same prefix/suffix as KeyvGithub, with filename: (k) => k for raw paths
+ * const dirStore = new KeyvDirStore("./cache", {
+ *   prefix: "data/",
+ *   suffix: ".json",
+ *   filename: (k) => k,  // use key as-is, no hashing
+ * });
+ * // Now dirStore uses same paths as KeyvGithub:
+ * // key "foo" -> ./cache/data/foo.json (local) and data/foo.json (GitHub)
+ *
  */
-export class KeyvDirStore<Value extends string> implements Keyv.Store<string> {
+export class KeyvDirStore<Value extends string> implements KeyvStoreAdapter {
   #dir: string;
   #cache: CacheMap<Value>;
   #ready: Promise<unknown>;
   #filename: (key: string) => string;
-  ext = ".json";
+  opts: Record<string, unknown> = {};
+  namespace?: string;
+  /** Path prefix prepended to every key (e.g. 'data/'). Defaults to ''. */
+  readonly prefix: string;
+  /** Path suffix appended to every key (e.g. '.json'). Defaults to '.json'. */
+  readonly suffix: string;
   constructor(
     /** dir to cache store
      * WARN: dont share this dir with other purpose
@@ -37,18 +56,23 @@ export class KeyvDirStore<Value extends string> implements Keyv.Store<string> {
     {
       cache = new Map(),
       filename,
-      ext,
+      prefix,
+      suffix,
     }: {
       cache?: CacheMap<Value>;
       filename?: (key: string) => string;
-      ext?: string;
-    } = {}
+      /** Path prefix prepended to every key (e.g. 'data/'). Use with filename: (k) => k for raw paths. */
+      prefix?: string;
+      /** Path suffix appended to every key (e.g. '.json'). Defaults to '.json'. Use with filename: (k) => k for raw paths. */
+      suffix?: string;
+    } = {},
   ) {
     this.#ready = mkdir(dir, { recursive: true }).catch(() => {});
     this.#cache = cache;
     this.#dir = dir;
     this.#filename = filename ?? this.#defaultFilename;
-    this.ext = ext ?? this.ext;
+    this.prefix = prefix ?? "";
+    this.suffix = suffix ?? ".json";
   }
   #defaultFilename(key: string) {
     // use dir as hash salt to avoid collisions
@@ -58,12 +82,13 @@ export class KeyvDirStore<Value extends string> implements Keyv.Store<string> {
     return name;
   }
   #path(key: string) {
-    return path.join(
-      this.#dir,
-      sanitizeFilename(this.#filename(key) + this.ext)
-    );
+    const filename = this.#filename(key);
+    // Sanitize filename+suffix for safety; prefix can have slashes for nested paths
+    const safeFilename = sanitizeFilename(filename + this.suffix);
+    const relativePath = this.prefix + safeFilename;
+    return path.join(this.#dir, relativePath);
   }
-  async get(key: string) {
+  async get<T = Value>(key: string): Promise<T | undefined> {
     // read memory
     const memCached = this.#cache.get(key);
     if (memCached) {
@@ -71,7 +96,7 @@ export class KeyvDirStore<Value extends string> implements Keyv.Store<string> {
       if (memCached.expires && memCached.expires < Date.now()) {
         await this.delete(key);
       } else {
-        return memCached.value;
+        return memCached.value as T;
       }
     }
     // read file cache
@@ -87,7 +112,7 @@ export class KeyvDirStore<Value extends string> implements Keyv.Store<string> {
         return undefined;
       }
     }
-    return await readFile(path, "utf8").catch(() => undefined);
+    return await readFile(path, "utf8").catch(() => undefined) as T | undefined;
   }
   async set(key: string, value: Value, ttl?: number) {
     if (!value) return await this.delete(key);
@@ -97,10 +122,11 @@ export class KeyvDirStore<Value extends string> implements Keyv.Store<string> {
     this.#cache.set(key, { value, expires });
     // save to file
     await this.#ready;
-    // console.log({ key, value, expires });
-    await mkdir(this.#dir, { recursive: true }).catch(() => {});
-    await writeFile(this.#path(key), value); // create a expired file
-    await utimes(this.#path(key), new Date(), new Date(expires ?? 0)); // set expires time as mtime (0 as never expired)
+    const filePath = this.#path(key);
+    // create parent directories for nested paths (e.g. data/sub/key.json)
+    await mkdir(path.dirname(filePath), { recursive: true }).catch(() => {});
+    await writeFile(filePath, value); // create a expired file
+    await utimes(filePath, new Date(), new Date(expires ?? 0)); // set expires time as mtime (0 as never expired)
     return true;
   }
   async delete(key: string) {
@@ -124,4 +150,8 @@ export class KeyvDirStore<Value extends string> implements Keyv.Store<string> {
   static deserialize(str: string): DeserializedData<any> {
     return { value: JSON.parse(str), expires: undefined };
   }
+  // IEventEmitter implementation (required by KeyvStoreAdapter)
+  on(_event: string, _listener: (...args: any[]) => void): this {
+    return this;
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "keyv-dir-store",
-  "version": "0.0.9",
+  "version": "1.0.0",
   "description": "High performance Filesystem Keyv Store, caches each key-value pair into a $key.json. and more! *.JSON, *.YAML, *.CSV is also avaliable.",
   "keywords": [
     "keyv",
@@ -37,20 +37,20 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@types/node": "^20.14.2",
+    "@types/node": "^25.3.3",
     "md5": "^2.3.0",
     "sanitize-filename": "^1.6.3",
-    "yaml": "^2.4.5"
+    "yaml": "^2.8.2"
   },
   "devDependencies": {
-    "@types/bun": "^1.1.17",
-    "@types/jest": "^29.5.14",
-    "@types/md5": "^2.3.5",
+    "@types/bun": "^1.3.9",
+    "@types/jest": "^30.0.0",
+    "@types/md5": "^2.3.6",
     "husky": "^9.1.7",
-    "semantic-release": "^24.2.1",
-    "typescript": "^5.7.3"
+    "semantic-release": "^25.0.3",
+    "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "keyv": "^4.5.4"
+    "keyv": "^5.6.0"
   }
 }