keyv-dir-store 0.1.0 → 1.0.0

package/README.md

@@ -75,7 +75,7 @@ import { KeyvDirStore } from "keyv-dir-store";
 import { KeyvDirStoreAsJSON } from "keyv-dir-store/KeyvDirStoreAsJSON";
 
 const keyv = new Keyv({
-  store: new KeyvDirStore(".cache/kv", { ext: ".json" }),
+  store: new KeyvDirStore(".cache/kv", { suffix: ".json" }),
   ...KeyvDirStoreAsJSON,
 });
 ```
@@ -88,7 +88,7 @@ import { KeyvDirStore } from "keyv-dir-store";
 import { KeyvDirStoreAsYaml } from "keyv-dir-store/KeyvDirStoreAsYaml";
 
 const keyv = new Keyv({
-  store: new KeyvDirStore(".cache/kv", { ext: ".yaml" }),
+  store: new KeyvDirStore(".cache/kv", { suffix: ".yaml" }),
   ...KeyvDirStoreAsYaml,
 });
 ```
@@ -101,7 +101,7 @@ import { KeyvDirStore } from "keyv-dir-store";
 import * as d3 from "d3";
 
 const keyv = new Keyv({
-  store: new KeyvDirStore(".cache/kv", { ext: ".csv" }),
+  store: new KeyvDirStore(".cache/kv", { suffix: ".csv" }),
   serialize: ({ value }) => d3.csvFormat(value),
   deserialize: (str) => ({ value: d3.csvParse(str), expires: undefined }),
 });
@@ -115,7 +115,7 @@ import { KeyvDirStore } from "keyv-dir-store";
 import * as d3 from "d3";
 
 const keyv = new Keyv({
-  store: new KeyvDirStore(".cache/kv", { ext: ".tsv" }),
+  store: new KeyvDirStore(".cache/kv", { suffix: ".tsv" }),
   serialize: ({ value }) => d3.tsvFormat(value),
   deserialize: (str) => ({ value: d3.tsvParse(str), expires: undefined }),
 });
@@ -133,9 +133,8 @@ Creates a new KeyvDirStore instance.
 - `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)
+  - `suffix` (string, optional): Path suffix appended to every key (default: `.json`)
 
 #### Example with Custom Options
 
@@ -145,8 +144,8 @@ import { KeyvDirStore } from "keyv-dir-store";
 
 const keyv = new Keyv({
   store: new KeyvDirStore(".cache/kv", {
-    // Custom file extension
-    ext: ".data",
+    // Custom file suffix/extension
+    suffix: ".data",
 
     // Custom filename generator
     filename: (key) => `custom-prefix-${key}`,
@@ -186,6 +185,13 @@ const store = KeyvNest(
 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:

package/dist/index.js

@@ -344,13 +344,13 @@ class KeyvDirStore {
   #cache;
   #ready;
   #filename;
-  ext = ".json";
+  opts = {};
+  namespace;
   prefix;
   suffix;
   constructor(dir, {
     cache = new Map,
     filename,
-    ext,
     prefix,
     suffix
   } = {}) {
@@ -358,9 +358,8 @@ class KeyvDirStore {
     this.#cache = cache;
     this.#dir = dir;
     this.#filename = filename ?? this.#defaultFilename;
-    this.ext = ext ?? this.ext;
     this.prefix = prefix ?? "";
-    this.suffix = suffix ?? "";
+    this.suffix = suffix ?? ".json";
   }
   #defaultFilename(key) {
     const readableName = import_sanitize_filename.default(key).slice(0, 16);
@@ -370,8 +369,7 @@ class KeyvDirStore {
   }
   #path(key) {
     const filename = this.#filename(key);
-    const ext = this.suffix || this.ext;
-    const safeFilename = import_sanitize_filename.default(filename + ext);
+    const safeFilename = import_sanitize_filename.default(filename + this.suffix);
     const relativePath = this.prefix + safeFilename;
     return path.join(this.#dir, relativePath);
   }
@@ -431,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,6 +8,10 @@ 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 Basic usage
@@ -32,15 +36,16 @@ type CacheMap<Value> = Map<string, DeserializedData<Value>>;
  * // 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 ''. Overrides ext when set. */
+  /** Path suffix appended to every key (e.g. '.json'). Defaults to '.json'. */
   readonly suffix: string;
   constructor(
     /** dir to cache store
@@ -51,16 +56,14 @@ 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. */
+      /** Path suffix appended to every key (e.g. '.json'). Defaults to '.json'. Use with filename: (k) => k for raw paths. */
       suffix?: string;
     } = {},
   ) {
@@ -68,9 +71,8 @@ export class KeyvDirStore<Value extends string> implements Keyv.Store<string> {
     this.#cache = cache;
     this.#dir = dir;
     this.#filename = filename ?? this.#defaultFilename;
-    this.ext = ext ?? this.ext;
     this.prefix = prefix ?? "";
-    this.suffix = suffix ?? "";
+    this.suffix = suffix ?? ".json";
   }
   #defaultFilename(key: string) {
     // use dir as hash salt to avoid collisions
@@ -81,13 +83,12 @@ export class KeyvDirStore<Value extends string> implements Keyv.Store<string> {
   }
   #path(key: string) {
     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);
+    // 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) {
@@ -95,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
@@ -111,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);
@@ -149,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.1.0",
+  "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",