fastkv 2.0.0 → 2.0.2

package/README.md

@@ -6,13 +6,12 @@
 
 FastKV is a key-value store which offers the following features:
 
--   Supports temporary in-memory storage 🕒
--   Supports persistent storage with JSON files 📁
--   Lightweight with no dependencies ⚡
+- Supports storage in memory and in JSON files
+- Lightweight with zero dependencies
 
 ## Installation
 
-Get FastKV via npm using your favourite package manager:
+Get FastKV via your package manager.
 
 ```sh
 npm install fastkv
@@ -26,25 +25,41 @@ bun add fastkv
 
 ## Example
 
-```js
-import { KV } from 'fastkv';
+```ts
+import { KV } from "fastkv";
 
-// For TypeScript users, the KV supports generics:
-// const example = new KV<string>();
-// Or: example.get<string>('my-key-name');
+// Type safety (optional; for TypeScript)
+interface User {
+    name: string;
+    age?: number;
+    settings?: { theme: string };
+}
 
-const kv = new KV('./db.json'); // Save the data. Path resolves with process.cwd()
-const cache = new KV('::memory::'); // Keep the data in the system's memory.
+const kv = new KV<User>({ path: "./db.json" }); // Persistent storage
+const cache = new KV<User>(); // In-memory store (no path provided)
 
-// Set data
-kv.set('userSettings', { theme: 'dark' });
+// Set or overwrite data
+await kv.set("user1", { name: "Alice", age: 25 });
 
-// Retreive data by a key
-kv.get('userSettings'); // -> { theme: 'dark' }
+// Get data by key
+const user = await kv.get("user1"); // -> { __id: ..., key: 'user1', value: { name: 'Alice', age: 25 } }
 
-// Retreive all data
-kv.all(); // -> [{ key: 'userSettings', value: { theme: 'dark' } }]
+// Get nested values
+const theme = await kv.get("user1.settings.theme"); // -> 'dark'
 
-// Clear the store
-kv.clear();
+// Upsert (update or create)
+await kv.upsert({
+    where: { name: "Alice" }, // filter
+    create: { name: "Alice", age: 25, settings: { theme: "dark" } }, // if not exists
+    update: { age: 26 }, // partial update if exists
+});
+
+// Find entries by key or value
+const usersNamedAlice = await kv.find({ where: "Alice", in: "value" });
+
+// Get all entries
+const allEntries = await kv.all();
+
+// Clear all entries
+await kv.clear();
 ```

package/dist/index.d.mts

@@ -1,3 +1,7 @@
+interface KVOptions {
+    path?: string;
+    prettify?: boolean;
+}
 type Entry<T = any> = {
     __id: string;
     key: string;
@@ -9,10 +13,7 @@ type DeepPartial<T> = {
 declare class KV<T = any> {
     #private;
     path?: string;
-    constructor(options?: {
-        path?: string;
-        prettify?: boolean;
-    });
+    constructor(options?: KVOptions);
     set(key: string, value: T): Promise<Entry<T>>;
     upsert(options: {
         where: DeepPartial<T> | string;

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+interface KVOptions {
+    path?: string;
+    prettify?: boolean;
+}
 type Entry<T = any> = {
     __id: string;
     key: string;
@@ -9,10 +13,7 @@ type DeepPartial<T> = {
 declare class KV<T = any> {
     #private;
     path?: string;
-    constructor(options?: {
-        path?: string;
-        prettify?: boolean;
-    });
+    constructor(options?: KVOptions);
     set(key: string, value: T): Promise<Entry<T>>;
     upsert(options: {
         where: DeepPartial<T> | string;

package/dist/index.js

@@ -42,6 +42,10 @@ var KV = class {
   #data = [];
   #ready;
   #prettify;
+  /**
+   * Create a new KV instance
+   * @param options Configuration options
+   */
   constructor(options) {
     if (options?.prettify) {
       this.#prettify = options?.prettify;
@@ -55,15 +59,25 @@ var KV = class {
       this.#ready = Promise.resolve();
     }
   }
+  /**
+   * Load stored data from disk into memory, create a new empty store if file doesn't exist
+   */
   async #loadFromFile() {
     try {
       const content = await import_promises.default.readFile(this.path, "utf8");
       this.#data = JSON.parse(content);
-    } catch {
-      this.#data = [];
-      await this.#saveToFile();
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        this.#data = [];
+        await this.#saveToFile();
+      } else {
+        throw new Error("Failed to load database file: " + error.message);
+      }
     }
   }
+  /**
+   * Save in-memory data to disk if file path is provided
+   */
   async #saveToFile() {
     if (!this.path) return;
     await import_promises.default.writeFile(
@@ -72,17 +86,37 @@ var KV = class {
       "utf8"
     );
   }
+  /**
+   * Resolves dot-notation paths within objects
+   * @param object Base object
+   * @param path Dot-separated path string
+   * @returns Resolved value, or undefined
+   */
   #resolvePath(object, path2) {
     return path2.split(".").reduce((acc, part) => acc ? acc[part] : void 0, object);
   }
+  /**
+   * Compare a value against a partial filter object
+   * @param value Actual stored value
+   * @param where Partial value to match against
+   * @returns
+   */
   #matches(value, where) {
+    if (where === null) return value === null;
     if (typeof value !== typeof where) return false;
     if (typeof value === "object" && value !== null && where !== null) {
       return Object.entries(where).every(([k, v]) => this.#matches(value[k], v));
     }
     return value === where;
   }
+  /**
+   * Set a value by key, creates a new entry or overrides existing one
+   * @param key Unique identifier
+   * @param value Data to store
+   * @returns
+   */
   async set(key, value) {
+    if (!key) throw new Error("Key cannot be empty");
     await this.#ready;
     const entry = this.#data.find((entry2) => entry2.key === key);
     if (entry) {
@@ -95,7 +129,17 @@ var KV = class {
     await this.#saveToFile();
     return newEntry;
   }
+  /**
+   * Update an existing entry or create a new one if not found
+   * @param options Upserting options
+   */
   async upsert(options) {
+    if (!options.create && !options.update) {
+      throw new Error("Upsert requires at least create or update to be provided");
+    }
+    if (typeof options.where === "string" && !options.where) {
+      throw new Error("Upsert key cannot be empty");
+    }
     await this.#ready;
     let entry;
     if (typeof options.where === "string") {
@@ -109,13 +153,25 @@ var KV = class {
       }
     } else {
       const key = typeof options.where === "string" ? options.where : (0, import_node_crypto.randomUUID)();
-      entry = { __id: (0, import_node_crypto.randomUUID)(), key, value: { ...options.create ?? {} } };
+      const baseValue = options.create ?? options.update ?? {};
+      entry = {
+        __id: (0, import_node_crypto.randomUUID)(),
+        key,
+        value: { ...baseValue }
+      };
       this.#data.push(entry);
     }
     await this.#saveToFile();
     return entry;
   }
+  /**
+   * Find entries by matching key or value
+   * @param options Search options
+   */
   async find(options) {
+    if (options.in && options.in !== "key" && options.in !== "value") {
+      throw new Error(`Invalid search field: ${options.in}`);
+    }
     await this.#ready;
     const field = options.in ?? "value";
     const where = options.where;
@@ -126,7 +182,12 @@ var KV = class {
       return this.#matches(entry.value, where);
     });
   }
+  /**
+   * Get an entry, supports nested values with dot notation
+   * @param query Key or path via dot notation
+   */
   async get(query) {
+    if (!query) throw new Error("Query string cannot be empty");
     await this.#ready;
     const [baseKey, ...rest] = query.split(".");
     const entry = this.#data.find((entry2) => entry2.key === baseKey);
@@ -134,10 +195,16 @@ var KV = class {
     if (rest.length === 0) return entry;
     return this.#resolvePath({ value: entry.value }, rest.join(".")) ?? null;
   }
+  /**
+   * Get all stored entries
+   */
   async all() {
     await this.#ready;
     return [...this.#data];
   }
+  /**
+   * Remove all entries
+   */
   async clear() {
     await this.#ready;
     this.#data = [];

package/dist/index.mjs

@@ -7,6 +7,10 @@ var KV = class {
   #data = [];
   #ready;
   #prettify;
+  /**
+   * Create a new KV instance
+   * @param options Configuration options
+   */
   constructor(options) {
     if (options?.prettify) {
       this.#prettify = options?.prettify;
@@ -20,15 +24,25 @@ var KV = class {
       this.#ready = Promise.resolve();
     }
   }
+  /**
+   * Load stored data from disk into memory, create a new empty store if file doesn't exist
+   */
   async #loadFromFile() {
     try {
       const content = await fs.readFile(this.path, "utf8");
       this.#data = JSON.parse(content);
-    } catch {
-      this.#data = [];
-      await this.#saveToFile();
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        this.#data = [];
+        await this.#saveToFile();
+      } else {
+        throw new Error("Failed to load database file: " + error.message);
+      }
     }
   }
+  /**
+   * Save in-memory data to disk if file path is provided
+   */
   async #saveToFile() {
     if (!this.path) return;
     await fs.writeFile(
@@ -37,17 +51,37 @@ var KV = class {
       "utf8"
     );
   }
+  /**
+   * Resolves dot-notation paths within objects
+   * @param object Base object
+   * @param path Dot-separated path string
+   * @returns Resolved value, or undefined
+   */
   #resolvePath(object, path2) {
     return path2.split(".").reduce((acc, part) => acc ? acc[part] : void 0, object);
   }
+  /**
+   * Compare a value against a partial filter object
+   * @param value Actual stored value
+   * @param where Partial value to match against
+   * @returns
+   */
   #matches(value, where) {
+    if (where === null) return value === null;
     if (typeof value !== typeof where) return false;
     if (typeof value === "object" && value !== null && where !== null) {
       return Object.entries(where).every(([k, v]) => this.#matches(value[k], v));
     }
     return value === where;
   }
+  /**
+   * Set a value by key, creates a new entry or overrides existing one
+   * @param key Unique identifier
+   * @param value Data to store
+   * @returns
+   */
   async set(key, value) {
+    if (!key) throw new Error("Key cannot be empty");
     await this.#ready;
     const entry = this.#data.find((entry2) => entry2.key === key);
     if (entry) {
@@ -60,7 +94,17 @@ var KV = class {
     await this.#saveToFile();
     return newEntry;
   }
+  /**
+   * Update an existing entry or create a new one if not found
+   * @param options Upserting options
+   */
   async upsert(options) {
+    if (!options.create && !options.update) {
+      throw new Error("Upsert requires at least create or update to be provided");
+    }
+    if (typeof options.where === "string" && !options.where) {
+      throw new Error("Upsert key cannot be empty");
+    }
     await this.#ready;
     let entry;
     if (typeof options.where === "string") {
@@ -74,13 +118,25 @@ var KV = class {
       }
     } else {
       const key = typeof options.where === "string" ? options.where : randomUUID();
-      entry = { __id: randomUUID(), key, value: { ...options.create ?? {} } };
+      const baseValue = options.create ?? options.update ?? {};
+      entry = {
+        __id: randomUUID(),
+        key,
+        value: { ...baseValue }
+      };
       this.#data.push(entry);
     }
     await this.#saveToFile();
     return entry;
   }
+  /**
+   * Find entries by matching key or value
+   * @param options Search options
+   */
   async find(options) {
+    if (options.in && options.in !== "key" && options.in !== "value") {
+      throw new Error(`Invalid search field: ${options.in}`);
+    }
     await this.#ready;
     const field = options.in ?? "value";
     const where = options.where;
@@ -91,7 +147,12 @@ var KV = class {
       return this.#matches(entry.value, where);
     });
   }
+  /**
+   * Get an entry, supports nested values with dot notation
+   * @param query Key or path via dot notation
+   */
   async get(query) {
+    if (!query) throw new Error("Query string cannot be empty");
     await this.#ready;
     const [baseKey, ...rest] = query.split(".");
     const entry = this.#data.find((entry2) => entry2.key === baseKey);
@@ -99,10 +160,16 @@ var KV = class {
     if (rest.length === 0) return entry;
     return this.#resolvePath({ value: entry.value }, rest.join(".")) ?? null;
   }
+  /**
+   * Get all stored entries
+   */
   async all() {
     await this.#ready;
     return [...this.#data];
   }
+  /**
+   * Remove all entries
+   */
   async clear() {
     await this.#ready;
     this.#data = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fastkv",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "publishConfig": {
     "access": "public"
   },
@@ -9,12 +9,12 @@
     "package.json",
     "README.md"
   ],
-  "description": "A key-value store, helpful for caches in apps.",
+  "description": "A simple key-value store with optional JSON file storing",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
   "repository": {
-    "url": "https://github.com/m1-dev/fastkv"
+    "url": "https://github.com/e60m5ss/fastkv"
   },
   "keywords": [
     "kv",