keyv-dir-store 0.0.8 → 0.1.0

package/README.md

@@ -1,41 +1,211 @@
 # 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
+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)
+
+```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", { ext: ".json" }),
+  ...KeyvDirStoreAsJSON,
+});
+```
+
+#### Store with YAML (using provided helper)
 
 ```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";
+import { KeyvDirStoreAsYaml } from "keyv-dir-store/KeyvDirStoreAsYaml";
+
+const keyv = new Keyv({
+  store: new KeyvDirStore(".cache/kv", { ext: ".yaml" }),
+  ...KeyvDirStoreAsYaml,
 });
+```
+
+#### Store Object Lists with CSV
+
+```ts
+import Keyv from "keyv";
+import { KeyvDirStore } from "keyv-dir-store";
+import * as d3 from "d3";
 
-// Store each object list with CSV
-new Keyv({
+const keyv = new Keyv({
   store: new KeyvDirStore(".cache/kv", { ext: ".csv" }),
   serialize: ({ value }) => d3.csvFormat(value),
   deserialize: (str) => ({ value: d3.csvParse(str), expires: undefined }),
 });
+```
 
-// Store each object list with TSV
-new Keyv({
+#### 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", { ext: ".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
 
-// 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 }),
+### `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
+  - `ext` (string, optional): File extension to use (default: `.json`)
+  - `prefix` (string, optional): Path prefix prepended to every key (e.g. `'data/'`)
+  - `suffix` (string, optional): Path suffix appended to every key (overrides `ext` when set)
+
+#### 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 extension
+    ext: ".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
+
+## 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);
@@ -331,17 +345,22 @@ class KeyvDirStore {
   #ready;
   #filename;
   ext = ".json";
+  prefix;
+  suffix;
   constructor(dir, {
     cache = new Map,
     filename,
-    ext
+    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 ?? "";
   }
   #defaultFilename(key) {
     const readableName = import_sanitize_filename.default(key).slice(0, 16);
@@ -350,7 +369,11 @@ 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 ext = this.suffix || this.ext;
+    const safeFilename = import_sanitize_filename.default(filename + ext);
+    const relativePath = this.prefix + safeFilename;
+    return path.join(this.#dir, relativePath);
   }
   async get(key) {
     const memCached = this.#cache.get(key);
@@ -383,10 +406,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) {

package/index.ts

@@ -10,7 +10,7 @@ type CacheMap<Value> = Map<string, DeserializedData<Value>>;
  *
  * 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,6 +21,16 @@ 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> {
   #dir: string;
@@ -28,6 +38,10 @@ export class KeyvDirStore<Value extends string> implements Keyv.Store<string> {
   #ready: Promise<unknown>;
   #filename: (key: string) => string;
   ext = ".json";
+  /** 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 ''. Overrides ext when set. */
+  readonly suffix: string;
   constructor(
     /** dir to cache store
      * WARN: dont share this dir with other purpose
@@ -38,18 +52,25 @@ 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'). Overrides ext when set. 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 ?? "";
   }
   #defaultFilename(key: string) {
     // use dir as hash salt to avoid collisions
@@ -59,10 +80,12 @@ 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);
+    const ext = this.suffix || this.ext;  // suffix overrides ext when set
+    // Sanitize filename+ext for safety; prefix can have slashes for nested paths
+    const safeFilename = sanitizeFilename(filename + ext);
+    const relativePath = this.prefix + safeFilename;
+    return path.join(this.#dir, relativePath);
   }
   async get(key: string) {
     // read memory
@@ -98,10 +121,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) {
@@ -116,7 +140,6 @@ export class KeyvDirStore<Value extends string> implements Keyv.Store<string> {
   async has(key: string) {
     return undefined !== (await this.get(key));
   }
-
   // Save expires into mtime, and value into file
   /** @deprecated use KeyvDirStoreJSON */
   static serialize({ value }: DeserializedData<any>): string {

package/package.json

@@ -1,12 +1,28 @@
 {
   "name": "keyv-dir-store",
-  "version": "0.0.8",
+  "version": "0.1.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",
+    "keyv-store",
+    "dir"
+  ],
+  "homepage": "https://github.com/snomiao/keyv-dir-store#readme",
+  "bugs": {
+    "url": "https://github.com/snomiao/keyv-dir-store/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/snomiao/keyv-dir-store.git"
+  },
+  "license": "MIT",
   "author": "snomiao <snomiao@gmail.com>",
   "type": "module",
   "exports": {
     "import": "./dist/index.js",
     "types": "./index.ts"
   },
+  "main": "index.js",
   "module": "index.ts",
   "types": "./index.ts",
   "files": [
@@ -15,26 +31,26 @@
   ],
   "scripts": {
     "build": "bun build index.ts --outdir=dist --target=bun",
+    "prepare": "husky",
     "prerelease": "bun run build && bun run test",
     "release": "bunx standard-version && git push --follow-tags && npm publish",
-    "test": "bun test",
-    "prepare": "husky"
+    "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.3",
-    "@types/jest": "^29.5.12",
-    "@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.4.5"
+    "semantic-release": "^25.0.3",
+    "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "keyv": "^4.5.4"
+    "keyv": "^5.6.0"
   }
 }