fastkv 1.0.0 → 2.0.1

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
@@ -20,29 +19,47 @@ npm install fastkv
 yarn add fastkv
 # or
 pnpm add fastkv
+# or
+bun add fastkv
 ```
 
 ## Example
 
-```js
-import { KV } from 'fastkv';
+```ts
+import { KV } from "fastkv";
+
+// Type safety (optional; for TypeScript)
+interface User {
+    name: string;
+    age?: number;
+    settings?: { theme: string };
+}
+
+const kv = new KV<User>({ path: "./db.json" }); // Persistent storage
+const cache = new KV<User>(); // In-memory store (no path provided)
+
+// Set or overwrite data
+await kv.set("user1", { name: "Alice", age: 25 });
 
-// For TypeScript users, the KV supports generics:
-// const example = new KV<string>();
-// Or: example.get<string>('my-key-name');
+// Get data by key
+const user = await kv.get("user1"); // -> { __id: ..., key: 'user1', value: { name: 'Alice', age: 25 } }
 
-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.
+// Get nested values
+const theme = await kv.get("user1.settings.theme"); // -> 'dark'
 
-// Set data
-kv.set('userSettings', { theme: 'dark' }); // -> KV
+// 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
+});
 
-// Retreive data by a key
-kv.get('userSettings'); // -> { theme: 'dark' }
+// Find entries by key or value
+const usersNamedAlice = await kv.find({ where: "Alice", in: "value" });
 
-// Retreive all data
-kv.all(); // -> [{ key: 'userSettings', value: { theme: 'dark' } }]
+// Get all entries
+const allEntries = await kv.all();
 
-// Clear the store
-kv.clear(); // -> KV
+// Clear all entries
+await kv.clear();
 ```

package/dist/index.d.mts

@@ -1,43 +1,32 @@
-type Entry<T> = {
+interface KVOptions {
+    path?: string;
+    prettify?: boolean;
+}
+type Entry<T = any> = {
+    __id: string;
     key: string;
     value: T;
 };
-/**
- * Represents a key-value store.
- * Initializing with `::memory::` uses in-memory storage.
- */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
 declare class KV<T = any> {
     #private;
-    /**
-     * Creates a new instance of the class.
-     * @param location - Where the data will be stored.
-     * Can be `::memory::` or a file location.
-     */
-    constructor(location?: string);
-    /**
-     * Sets a value to a key.
-     * @param key - The name of the key.
-     * @param value - The value to store.
-     * @returns The value.
-     */
-    set(key: string, value: T): T;
-    /**
-     * Gets data by a key.
-     * @param key - The existing key's name.
-     * @returns The found data, or null.
-     */
-    get<U = T>(key: string): U | null;
-    /**
-     * Gets all data in the store.
-     * @returns An array of Entry objects [{ key: string, value: T }].
-     */
-    all(): Entry<T>[];
-    /**
-     * Clears all data in the store.
-     * @returns The KV instance.
-     */
-    clear(): this;
+    path?: string;
+    constructor(options?: KVOptions);
+    set(key: string, value: T): Promise<Entry<T>>;
+    upsert(options: {
+        where: DeepPartial<T> | string;
+        create?: DeepPartial<T>;
+        update?: DeepPartial<T>;
+    }): Promise<Entry<T>>;
+    find(options: {
+        in?: "key" | "value";
+        where: T | string | number | boolean;
+    }): Promise<Entry<T>[]>;
+    get(query: string): Promise<Entry<T> | T | null>;
+    all(): Promise<Entry<T>[]>;
+    clear(): Promise<void>;
 }
-declare const _default: KV<any>;
 
-export { KV, _default as default };
+export { KV, KV as default };

package/dist/index.d.ts

@@ -1,43 +1,32 @@
-type Entry<T> = {
+interface KVOptions {
+    path?: string;
+    prettify?: boolean;
+}
+type Entry<T = any> = {
+    __id: string;
     key: string;
     value: T;
 };
-/**
- * Represents a key-value store.
- * Initializing with `::memory::` uses in-memory storage.
- */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
 declare class KV<T = any> {
     #private;
-    /**
-     * Creates a new instance of the class.
-     * @param location - Where the data will be stored.
-     * Can be `::memory::` or a file location.
-     */
-    constructor(location?: string);
-    /**
-     * Sets a value to a key.
-     * @param key - The name of the key.
-     * @param value - The value to store.
-     * @returns The value.
-     */
-    set(key: string, value: T): T;
-    /**
-     * Gets data by a key.
-     * @param key - The existing key's name.
-     * @returns The found data, or null.
-     */
-    get<U = T>(key: string): U | null;
-    /**
-     * Gets all data in the store.
-     * @returns An array of Entry objects [{ key: string, value: T }].
-     */
-    all(): Entry<T>[];
-    /**
-     * Clears all data in the store.
-     * @returns The KV instance.
-     */
-    clear(): this;
+    path?: string;
+    constructor(options?: KVOptions);
+    set(key: string, value: T): Promise<Entry<T>>;
+    upsert(options: {
+        where: DeepPartial<T> | string;
+        create?: DeepPartial<T>;
+        update?: DeepPartial<T>;
+    }): Promise<Entry<T>>;
+    find(options: {
+        in?: "key" | "value";
+        where: T | string | number | boolean;
+    }): Promise<Entry<T>[]>;
+    get(query: string): Promise<Entry<T> | T | null>;
+    all(): Promise<Entry<T>[]>;
+    clear(): Promise<void>;
 }
-declare const _default: KV<any>;
 
-export { KV, _default as default };
+export { KV, KV as default };

package/dist/index.js

@@ -1 +1,218 @@
-"use strict";var l=Object.create;var e=Object.defineProperty;var p=Object.getOwnPropertyDescriptor;var m=Object.getOwnPropertyNames;var y=Object.getPrototypeOf,f=Object.prototype.hasOwnProperty;var d=(r,t)=>{for(var i in t)e(r,i,{get:t[i],enumerable:!0})},c=(r,t,i,o)=>{if(t&&typeof t=="object"||typeof t=="function")for(let s of m(t))!f.call(r,s)&&s!==i&&e(r,s,{get:()=>t[s],enumerable:!(o=p(t,s))||o.enumerable});return r};var u=(r,t,i)=>(i=r!=null?l(y(r)):{},c(t||!r||!r.__esModule?e(i,"default",{value:r,enumerable:!0}):i,r)),g=r=>c(e({},"__esModule",{value:!0}),r);var b={};d(b,{KV:()=>n,default:()=>T});module.exports=g(b);var h=u(require("fs")),a=u(require("path")),n=class{#t;#r;constructor(t="::memory::"){this.#t=t,this.#r={},t!=="::memory::"&&(this.#t=a.default.resolve(process.cwd(),this.#t),this.#r=this.#s())}#s(){if(this.#t==="::memory::")return{};try{let t=h.default.readFileSync(this.#t,"utf8");return JSON.parse(t)||{}}catch{return{}}}#i(){this.#t!=="::memory::"&&h.default.writeFileSync(this.#t,JSON.stringify(this.#r),"utf8")}set(t,i){return this.#r[t]=i,this.#i(),i}get(t){return this.#r[t]??null}all(){return Object.entries(this.#r).map(([t,i])=>({key:t,value:i}))}clear(){return this.#r={},this.#i(),this}},T=new n;0&&(module.exports={KV});
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  KV: () => KV,
+  default: () => index_default
+});
+module.exports = __toCommonJS(index_exports);
+var import_node_crypto = require("crypto");
+var import_node_path = __toESM(require("path"));
+var import_promises = __toESM(require("fs/promises"));
+var KV = class {
+  path;
+  #data = [];
+  #ready;
+  #prettify;
+  /**
+   * Create a new KV instance
+   * @param options Configuration options
+   */
+  constructor(options) {
+    if (options?.prettify) {
+      this.#prettify = options?.prettify;
+    } else {
+      this.#prettify = false;
+    }
+    if (options?.path) {
+      this.path = import_node_path.default.resolve(process.cwd(), options.path);
+      this.#ready = this.#loadFromFile();
+    } else {
+      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 (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(
+      this.path,
+      JSON.stringify(this.#data, null, this.#prettify ? 2 : 0),
+      "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) {
+      entry.value = value;
+      await this.#saveToFile();
+      return entry;
+    }
+    const newEntry = { __id: (0, import_node_crypto.randomUUID)(), key, value };
+    this.#data.push(newEntry);
+    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") {
+      entry = this.#data.find((entry2) => entry2.key === options.where);
+    } else {
+      entry = this.#data.find((entry2) => this.#matches(entry2.value, options.where));
+    }
+    if (entry) {
+      if (options.update) {
+        entry.value = { ...entry.value, ...options.update };
+      }
+    } else {
+      const key = typeof options.where === "string" ? options.where : (0, import_node_crypto.randomUUID)();
+      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;
+    return this.#data.filter((entry) => {
+      if (field === "key") {
+        return typeof where === "string" && entry.key.includes(where);
+      }
+      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);
+    if (!entry) return null;
+    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 = [];
+    await this.#saveToFile();
+  }
+};
+var index_default = KV;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  KV
+});

package/dist/index.mjs

@@ -1 +1,183 @@
-import s from"node:fs";import e from"node:path";var i=class{#t;#r;constructor(t="::memory::"){this.#t=t,this.#r={},t!=="::memory::"&&(this.#t=e.resolve(process.cwd(),this.#t),this.#r=this.#s())}#s(){if(this.#t==="::memory::")return{};try{let t=s.readFileSync(this.#t,"utf8");return JSON.parse(t)||{}}catch{return{}}}#i(){this.#t!=="::memory::"&&s.writeFileSync(this.#t,JSON.stringify(this.#r),"utf8")}set(t,r){return this.#r[t]=r,this.#i(),r}get(t){return this.#r[t]??null}all(){return Object.entries(this.#r).map(([t,r])=>({key:t,value:r}))}clear(){return this.#r={},this.#i(),this}},a=new i;export{i as KV,a as default};
+// src/index.ts
+import { randomUUID } from "crypto";
+import path from "path";
+import fs from "fs/promises";
+var KV = class {
+  path;
+  #data = [];
+  #ready;
+  #prettify;
+  /**
+   * Create a new KV instance
+   * @param options Configuration options
+   */
+  constructor(options) {
+    if (options?.prettify) {
+      this.#prettify = options?.prettify;
+    } else {
+      this.#prettify = false;
+    }
+    if (options?.path) {
+      this.path = path.resolve(process.cwd(), options.path);
+      this.#ready = this.#loadFromFile();
+    } else {
+      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 (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(
+      this.path,
+      JSON.stringify(this.#data, null, this.#prettify ? 2 : 0),
+      "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) {
+      entry.value = value;
+      await this.#saveToFile();
+      return entry;
+    }
+    const newEntry = { __id: randomUUID(), key, value };
+    this.#data.push(newEntry);
+    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") {
+      entry = this.#data.find((entry2) => entry2.key === options.where);
+    } else {
+      entry = this.#data.find((entry2) => this.#matches(entry2.value, options.where));
+    }
+    if (entry) {
+      if (options.update) {
+        entry.value = { ...entry.value, ...options.update };
+      }
+    } else {
+      const key = typeof options.where === "string" ? options.where : randomUUID();
+      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;
+    return this.#data.filter((entry) => {
+      if (field === "key") {
+        return typeof where === "string" && entry.key.includes(where);
+      }
+      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);
+    if (!entry) return null;
+    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 = [];
+    await this.#saveToFile();
+  }
+};
+var index_default = KV;
+export {
+  KV,
+  index_default as default
+};

package/package.json

@@ -1,11 +1,18 @@
 {
   "name": "fastkv",
-  "version": "1.0.0",
+  "version": "2.0.1",
   "publishConfig": {
     "access": "public"
   },
-  "description": "A key-value store, helpful for caches in apps.",
-  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "package.json",
+    "README.md"
+  ],
+  "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"
   },
@@ -14,16 +21,29 @@
     "database",
     "json"
   ],
+  "prettier": {
+    "tabWidth": 4,
+    "printWidth": 95,
+    "arrowParens": "always",
+    "trailingComma": "es5",
+    "singleQuote": false,
+    "jsxSingleQuote": false,
+    "useTabs": false,
+    "semi": true
+  },
   "license": "MIT",
   "devDependencies": {
-    "@types/node": "^20.10.5",
-    "@underctrl/tsconfig": "^0.0.1",
+    "@types/node": "^20.11.16",
+    "prettier": "^3.2.5",
     "tsup": "^8.0.1",
     "typescript": "^5.3.3"
   },
   "scripts": {
     "build": "tsup",
-    "lint": "tsc --noEmit true",
-    "prepublish": "pnpm run build"
+    "lint": "tsc --noEmit; prettier . --check --ignore-path=.prettierignore",
+    "prepublish": "pnpm run build",
+    "format": "prettier . --write --ignore-path=.prettierignore",
+    "deploy:fastkv:beta": "pnpm publish --no-git-checks --access public --tag beta",
+    "deploy:fastkv:stable": "pnpm publish --no-git-checks --access public"
   }
 }