polystore 0.16.0 → 0.17.0

package/index.d.ts

@@ -52,28 +52,189 @@ declare class Store<TDefault extends Serializable = Serializable> {
     promise: Promise<Client> | null;
     client: Client;
     constructor(clientPromise?: any);
+    /**
+     * Save the data on an autogenerated key, can add expiration as well:
+     *
+     * ```js
+     * const key1 = await store.add("value1");
+     * const key2 = await store.add({ hello: "world" });
+     * const key3 = await store.add("value3", { expires: "1h" });
+     * ```
+     *
+     * **[→ Full .add() Docs](https://polystore.dev/documentation#add)**
+     */
     add(value: TDefault, options?: Options): Promise<string>;
     add<T extends TDefault>(value: T, options?: Options): Promise<string>;
+    /**
+     * Save the data on the given key, can add expiration as well:
+     *
+     * ```js
+     * const key = await store.set("key1", "value1");
+     * await store.set("key2", { hello: "world" });
+     * await store.set("key3", "value3", { expires: "1h" });
+     * ```
+     *
+     * **[→ Full .set() Docs](https://polystore.dev/documentation#set)**
+     */
     set(key: string, value: TDefault, options?: Options): Promise<string>;
     set<T extends TDefault>(key: string, value: T, options?: Options): Promise<string>;
+    /**
+     * Read a single value from the KV store:
+     *
+     * ```js
+     * const value1 = await store.get("key1");
+     * // null (doesn't exist or has expired)
+     * const value2 = await store.get("key2");
+     * // "value2"
+     * const value3 = await store.get("key3");
+     * // { hello: "world" }
+     * ```
+     *
+     * **[→ Full .get() Docs](https://polystore.dev/documentation#get)**
+     */
     get(key: string): Promise<TDefault | null>;
     get<T extends TDefault>(key: string): Promise<T | null>;
+    /**
+     * Check whether a key exists or not:
+     *
+     * ```js
+     * if (await store.has("key1")) { ... }
+     * ```
+     *
+     * If you are going to use the value, it's better to just read it:
+     *
+     * ```js
+     * const val = await store.get("key1");
+     * if (val) { ... }
+     * ```
+     *
+     * **[→ Full .has() Docs](https://polystore.dev/documentation#has)**
+     */
     has(key: string): Promise<boolean>;
+    /**
+     * Remove a single key and its value from the store:
+     *
+     * ```js
+     * const key = await store.del("key1");
+     * ```
+     *
+     * **[→ Full .del() Docs](https://polystore.dev/documentation#del)**
+     */
     del(key: string): Promise<string>;
+    /**
+     * An iterator that goes through all of the key:value pairs in the client
+     *
+     * ```js
+     * for await (const [key, value] of store) {
+     *   console.log(key, value);
+     * }
+     * ```
+     *
+     * **[→ Full Iterator Docs](https://polystore.dev/documentation#iterator)**
+     */
     [Symbol.asyncIterator](): AsyncGenerator<[string, TDefault], void, unknown>;
     [Symbol.asyncIterator]<T extends TDefault>(): AsyncGenerator<[
         string,
         T
     ], void, unknown>;
+    /**
+     * Return an array of the entries, in the [key, value] format:
+     *
+     * ```js
+     * const entries = await store.entries();
+     * // [["key1", "value1"], ["key2", { hello: "world" }], ...]
+     *
+     * // To limit it to a given prefix, use `.prefix()`:
+     * const sessions = await store.prefix("session:").entries();
+     * ```
+     *
+     * **[→ Full .entries() Docs](https://polystore.dev/documentation#entries)**
+     */
     entries(): Promise<[string, TDefault][]>;
     entries<T extends TDefault>(): Promise<[string, T][]>;
+    /**
+     * Return an array of the keys in the store:
+     *
+     * ```js
+     * const keys = await store.keys();
+     * // ["key1", "key2", ...]
+     *
+     * // To limit it to a given prefix, use `.prefix()`:
+     * const sessions = await store.prefix("session:").keys();
+     * ```
+     *
+     * **[→ Full .keys() Docs](https://polystore.dev/documentation#keys)**
+     */
     keys(): Promise<string[]>;
+    /**
+     * Return an array of the values in the store:
+     *
+     * ```js
+     * const values = await store.values();
+     * // ["value1", { hello: "world" }, ...]
+     *
+     * // To limit it to a given prefix, use `.prefix()`:
+     * const sessions = await store.prefix("session:").values();
+     * ```
+     *
+     * **[→ Full .values() Docs](https://polystore.dev/documentation#values)**
+     */
     values(): Promise<TDefault[]>;
     values<T extends TDefault>(): Promise<T[]>;
+    /**
+     * Return an object with the keys:values in the store:
+     *
+     * ```js
+     * const obj = await store.all();
+     * // { key1: "value1", key2: { hello: "world" }, ... }
+     *
+     * // To limit it to a given prefix, use `.prefix()`:
+     * const sessions = await store.prefix("session:").all();
+     * ```
+     *
+     * **[→ Full .all() Docs](https://polystore.dev/documentation#all)**
+     */
     all(): Promise<Record<string, TDefault>>;
     all<T extends TDefault>(): Promise<Record<string, T>>;
+    /**
+     * Delete all of the records of the store:
+     *
+     * ```js
+     * await store.clear();
+     * ```
+     *
+     * It's useful for cache invalidation, clearing the data, and testing.
+     *
+     * **[→ Full .clear() Docs](https://polystore.dev/documentation#clear)**
+     */
     clear(): Promise<void>;
+    /**
+     * Create a substore where all the keys are stored with
+     * the given prefix:
+     *
+     * ```js
+     * const session = store.prefix("session:");
+     * await session.set("key1", "value1");
+     * console.log(await session.entries());  // session.
+     * // [["key1", "value1"]]
+     * console.log(await store.entries());  // store.
+     * // [["session:key1", "value1"]]
+     * ```
+     *
+     * **[→ Full .prefix() Docs](https://polystore.dev/documentation#prefix)**
+     */
     prefix(prefix?: string): Store<TDefault>;
+    /**
+     * Stop the connection to the store, if any:
+     *
+     * ```js
+     * await session.set("key1", "value1");
+     * await store.close();
+     * await session.set("key2", "value2");  // error
+     * ```
+     *
+     * **[→ Full .close() Docs](https://polystore.dev/documentation#close)**
+     */
     close(): Promise<void>;
 }
 declare function createStore(): Store<Serializable>;

package/index.js

@@ -29,13 +29,14 @@ var Api = class extends Client {
     const exp = typeof expires === "number" ? `?expires=${expires}` : "";
     await this.#api(key, exp, "PUT", this.encode(value));
   };
-  del = async (key) => {
-    await this.#api(key, "", "DELETE");
-  };
+  del = (key) => this.#api(key, "", "DELETE");
   async *iterate(prefix = "") {
-    const data = await this.#api("", `?prefix=${encodeURIComponent(prefix)}`);
+    const data = await this.#api(
+      "",
+      `?prefix=${encodeURIComponent(prefix)}`
+    );
     for (let [key, value] of Object.entries(data || {})) {
-      if (value !== null && value !== void 0) {
+      if (value !== null) {
         yield [prefix + key, value];
       }
     }
@@ -48,13 +49,15 @@ var Cloudflare = class extends Client {
   EXPIRES = true;
   // Check whether the given store is a FILE-type
   static test = (client) => client?.constructor?.name === "KvNamespace" || client?.constructor?.name === "EdgeKVNamespace";
-  get = async (key) => this.decode(await this.client.get(key));
-  set = (key, data, opts) => {
+  get = async (key) => {
+    return this.decode(await this.client.get(key));
+  };
+  set = async (key, data, opts) => {
     const expirationTtl = opts.expires ? Math.round(opts.expires) : void 0;
     if (expirationTtl && expirationTtl < 60) {
       throw new Error("Cloudflare's min expiration is '60s'");
     }
-    return this.client.put(key, this.encode(data), { expirationTtl });
+    await this.client.put(key, this.encode(data), { expirationTtl });
   };
   del = (key) => this.client.delete(key);
   // Since we have pagination, we don't want to get all of the
@@ -84,7 +87,7 @@ var Cloudflare = class extends Client {
   entries = async (prefix = "") => {
     const keys = await this.keys(prefix);
     const values = await Promise.all(keys.map((k) => this.get(k)));
-    return keys.map((k, i) => [k, values[i]]);
+    return keys.map((k, i) => [k, values[i]]).filter((p) => p[1] !== null);
   };
 };
 
@@ -140,8 +143,13 @@ var Etcd = class extends Client {
   EXPIRES = false;
   // Check if this is the right class for the given client
   static test = (client) => client?.constructor?.name === "Etcd3";
-  get = (key) => this.client.get(key).json();
-  set = (key, value) => this.client.put(key).value(this.encode(value));
+  get = async (key) => {
+    const data = await this.client.get(key).json();
+    return data;
+  };
+  set = async (key, value) => {
+    await this.client.put(key).value(this.encode(value));
+  };
   del = (key) => this.client.delete().key(key).exec();
   async *iterate(prefix = "") {
     const keys = await this.client.getAll().prefix(prefix).keys();
@@ -149,7 +157,9 @@ var Etcd = class extends Client {
       yield [key, await this.get(key)];
     }
   }
-  keys = (prefix = "") => this.client.getAll().prefix(prefix).keys();
+  keys = (prefix = "") => {
+    return this.client.getAll().prefix(prefix).keys();
+  };
   entries = async (prefix = "") => {
     const keys = await this.keys(prefix);
     const values = await Promise.all(keys.map((k) => this.get(k)));
@@ -274,13 +284,16 @@ var Folder = class extends Client {
     });
   })();
   file = (key) => this.folder + key + ".json";
-  get = (key) => {
-    return this.fsp.readFile(this.file(key), "utf8").then(this.decode, noFileOk);
+  get = async (key) => {
+    const file = await this.fsp.readFile(this.file(key), "utf8").catch(noFileOk);
+    return this.decode(file);
   };
-  set = (key, value) => {
-    return this.fsp.writeFile(this.file(key), this.encode(value), "utf8");
+  set = async (key, value) => {
+    await this.fsp.writeFile(this.file(key), this.encode(value), "utf8");
+  };
+  del = async (key) => {
+    await this.fsp.unlink(this.file(key)).catch(noFileOk);
   };
-  del = (key) => this.fsp.unlink(this.file(key)).catch(noFileOk);
   async *iterate(prefix = "") {
     const all = await this.fsp.readdir(this.folder);
     const keys = all.filter((f) => f.startsWith(prefix) && f.endsWith(".json"));
@@ -288,7 +301,7 @@ var Folder = class extends Client {
       const key = name.slice(0, -".json".length);
       try {
         const data = await this.get(key);
-        yield [key, data];
+        if (data !== null && data !== void 0) yield [key, data];
       } catch {
         continue;
       }
@@ -428,25 +441,32 @@ var SQLite = class extends Client {
   // This one is doing manual time management internally even though
   // sqlite does not natively support expirations. This is because it does
   // support creating a `expires_at:Date` column that makes managing
-  //  expirations much easier, so it's really "somewhere in between"
+  // expirations much easier, so it's really "somewhere in between"
   EXPIRES = true;
-  static test = (client) => typeof client?.prepare === "function";
-  constructor(c) {
-    if (typeof c?.prepare("SELECT 1").get === "function") {
-      super({
-        run: (sql, ...args) => c.prepare(sql).run(...args),
-        get: (sql, ...args) => c.prepare(sql).get(...args),
-        all: (sql, ...args) => c.prepare(sql).all(...args)
-      });
-      return;
-    }
-    super(c);
-  }
-  get = (id) => {
-    const row = this.client.get(
-      `SELECT value, expires_at FROM kv WHERE id = ?`,
-      id
+  // The table name to use
+  table = "kv";
+  // Make sure the folder already exists, so attempt to create it
+  // It fails if it already exists, hence the catch case
+  promise = (async () => {
+    if (!/^[a-zA-Z_]+$/.test(this.table)) {
+      throw new Error(`Invalid table name ${this.table}`);
+    }
+    this.client.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.table} (
+        id TEXT PRIMARY KEY,
+        value TEXT NOT NULL,
+        expires_at INTEGER
+      )
+    `);
+    this.client.exec(
+      `CREATE INDEX IF NOT EXISTS idx_${this.table}_expires_at ON ${this.table} (expires_at)`
     );
+  })();
+  static test = (client) => {
+    return typeof client?.prepare === "function" && typeof client?.exec === "function";
+  };
+  get = (id) => {
+    const row = this.client.prepare(`SELECT value, expires_at FROM kv WHERE id = ?`).get(id);
     if (!row) return null;
     if (row.expires_at && row.expires_at < Date.now()) {
       this.del(id);
@@ -457,21 +477,15 @@ var SQLite = class extends Client {
   set = (id, data, { expires } = {}) => {
     const value = this.encode(data);
     const expires_at = expires ? Date.now() + expires * 1e3 : null;
-    this.client.run(
-      `INSERT INTO kv (id, value, expires_at)
-        VALUES (?, ?, ?)
-        ON CONFLICT(id)
-        DO UPDATE SET value = excluded.value, expires_at = excluded.expires_at`,
-      id,
-      value,
-      expires_at
-    );
+    this.client.prepare(
+      `INSERT INTO kv (id, value, expires_at) VALUES (?, ?, ?) ON CONFLICT(id) DO UPDATE SET value = excluded.value, expires_at = excluded.expires_at`
+    ).run(id, value, expires_at);
   };
-  del = (id) => {
-    this.client.run(`DELETE FROM kv WHERE id = ?`, id);
+  del = async (id) => {
+    await this.client.prepare(`DELETE FROM kv WHERE id = ?`).run(id);
   };
   has = (id) => {
-    const row = this.client.get(`SELECT expires_at FROM kv WHERE id = ?`, id);
+    const row = this.client.prepare(`SELECT expires_at FROM kv WHERE id = ?`).get(id);
     if (!row) return false;
     if (row.expires_at && row.expires_at < Date.now()) {
       this.del(id);
@@ -481,32 +495,27 @@ var SQLite = class extends Client {
   };
   *iterate(prefix = "") {
     this.#clearExpired();
-    const sql = `
-      SELECT id, value FROM kv
-      WHERE (expires_at IS NULL OR expires_at > ?)
-        ${prefix ? "AND id LIKE ?" : ""}
+    const sql = `SELECT id, value FROM kv WHERE (expires_at IS NULL OR expires_at > ?) ${prefix ? "AND id LIKE ?" : ""}
     `;
     const params = prefix ? [Date.now(), `${prefix}%`] : [Date.now()];
-    for (const row of this.client.all(sql, ...params)) {
+    for (const row of this.client.prepare(sql).all(...params)) {
       yield [row.id, this.decode(row.value)];
     }
   }
   keys = (prefix = "") => {
     this.#clearExpired();
-    const sql = `
-      SELECT id FROM kv
-      WHERE (expires_at IS NULL OR expires_at > ?)
-        ${prefix ? "AND id LIKE ?" : ""}
+    const sql = `SELECT id FROM kv WHERE (expires_at IS NULL OR expires_at > ?)
+${prefix ? "AND id LIKE ?" : ""}
     `;
     const params = prefix ? [Date.now(), `${prefix}%`] : [Date.now()];
-    const rows = this.client.all(sql, ...params);
+    const rows = this.client.prepare(sql).all(...params);
     return rows.map((r) => r.id);
   };
   #clearExpired = () => {
-    this.client.run(`DELETE FROM kv WHERE expires_at < ?`, Date.now());
+    this.client.prepare(`DELETE FROM kv WHERE expires_at < ?`).run(Date.now());
   };
   clearAll = () => {
-    this.client.run(`DELETE FROM kv`);
+    this.client.exec(`DELETE FROM kv`);
   };
   close = () => {
     this.client.close?.();
@@ -686,6 +695,22 @@ var Store = class _Store {
       return data.value;
     }
   }
+  /**
+   * Check whether a key exists or not:
+   *
+   * ```js
+   * if (await store.has("key1")) { ... }
+   * ```
+   *
+   * If you are going to use the value, it's better to just read it:
+   *
+   * ```js
+   * const val = await store.get("key1");
+   * if (val) { ... }
+   * ```
+   *
+   * **[→ Full .has() Docs](https://polystore.dev/documentation#has)**
+   */
   async has(key) {
     await this.promise;
     const id = this.PREFIX + key;
@@ -694,6 +719,15 @@ var Store = class _Store {
     }
     return await this.get(key) !== null;
   }
+  /**
+   * Remove a single key and its value from the store:
+   *
+   * ```js
+   * const key = await store.del("key1");
+   * ```
+   *
+   * **[→ Full .del() Docs](https://polystore.dev/documentation#del)**
+   */
   async del(key) {
     await this.promise;
     const id = this.PREFIX + key;
@@ -752,6 +786,19 @@ var Store = class _Store {
       return list;
     }
   }
+  /**
+   * Return an array of the keys in the store:
+   *
+   * ```js
+   * const keys = await store.keys();
+   * // ["key1", "key2", ...]
+   *
+   * // To limit it to a given prefix, use `.prefix()`:
+   * const sessions = await store.prefix("session:").keys();
+   * ```
+   *
+   * **[→ Full .keys() Docs](https://polystore.dev/documentation#keys)**
+   */
   async keys() {
     await this.promise;
     if (this.client.keys) {
@@ -776,6 +823,17 @@ var Store = class _Store {
     const entries = await this.entries();
     return Object.fromEntries(entries);
   }
+  /**
+   * Delete all of the records of the store:
+   *
+   * ```js
+   * await store.clear();
+   * ```
+   *
+   * It's useful for cache invalidation, clearing the data, and testing.
+   *
+   * **[→ Full .clear() Docs](https://polystore.dev/documentation#clear)**
+   */
   async clear() {
     await this.promise;
     if (!this.PREFIX && this.client.clearAll) {
@@ -787,6 +845,21 @@ var Store = class _Store {
     const keys = await this.keys();
     await Promise.all(keys.map((key) => this.del(key)));
   }
+  /**
+   * Create a substore where all the keys are stored with
+   * the given prefix:
+   *
+   * ```js
+   * const session = store.prefix("session:");
+   * await session.set("key1", "value1");
+   * console.log(await session.entries());  // session.
+   * // [["key1", "value1"]]
+   * console.log(await store.entries());  // store.
+   * // [["session:key1", "value1"]]
+   * ```
+   *
+   * **[→ Full .prefix() Docs](https://polystore.dev/documentation#prefix)**
+   */
   prefix(prefix = "") {
     const store = new _Store(
       Promise.resolve(this.promise).then(() => this.client)
@@ -794,6 +867,17 @@ var Store = class _Store {
     store.PREFIX = this.PREFIX + prefix;
     return store;
   }
+  /**
+   * Stop the connection to the store, if any:
+   *
+   * ```js
+   * await session.set("key1", "value1");
+   * await store.close();
+   * await session.set("key2", "value2");  // error
+   * ```
+   *
+   * **[→ Full .close() Docs](https://polystore.dev/documentation#close)**
+   */
   async close() {
     await this.promise;
     if (this.client.close) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polystore",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "A small compatibility layer for many popular KV stores like localStorage, Redis, FileSystem, etc.",
   "homepage": "https://polystore.dev/",
   "repository": "https://github.com/franciscop/polystore.git",
@@ -16,11 +16,13 @@
     "index.d.ts"
   ],
   "scripts": {
-    "analyze": "npm run build && esbuild src/index.ts --bundle --packages=external --format=esm --minify --outfile=index.min.js && gzip-size index.min.js && rm index.min.js",
+    "analyze": "npm run build && esbuild src/index.ts --bundle --packages=external --format=esm --minify --outfile=index.min.js && echo 'Final size:' && gzip-size index.min.js && rm index.min.js",
     "build": "bunx tsup src/index.ts --format esm --dts --out-dir . --target node24",
     "lint": "npx tsc --noEmit",
     "start": "bun test --watch",
-    "test": "bun test",
+    "test": "npm run test:bun && npm run test:jest",
+    "test:bun": "bun test ./test/index.test.ts",
+    "test:jest": "jest ./test/index.test.ts --detectOpenHandles --forceExit",
     "run:db": "etcd",
     "run:server": "bun ./src/server.ts"
   },
@@ -35,21 +37,27 @@
   "license": "MIT",
   "devDependencies": {
     "@deno/kv": "^0.8.1",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/bun": "^1.3.3",
+    "@types/jest": "^30.0.0",
     "@types/jsdom": "^27.0.0",
-    "better-sqlite3": "^12.5.0",
+    "better-sqlite3": "^12.6.0",
     "check-dts": "^0.8.0",
-    "cross-fetch": "^4.0.0",
+    "cross-fetch": "^4.1.0",
     "dotenv": "^16.3.1",
     "edge-mock": "^0.0.15",
     "esbuild": "^0.27.0",
     "etcd3": "^1.1.2",
     "gzip-size-cli": "^5.1.0",
+    "jest": "^30.2.0",
     "jsdom": "^27.2.0",
     "level": "^8.0.1",
     "localforage": "^1.10.0",
     "redis": "^4.6.10",
-    "tsup": "^8.5.1"
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
   },
   "documentation": {
     "title": "🏬 Polystore - A universal library for standardizing any KV-store",

package/readme.md

@@ -8,45 +8,44 @@ const store1 = kv(new Map()); // in-memory
 const store2 = kv(localStorage); // Persist in the browser
 const store3 = kv(redisClient); // Use a Redis client for backend persistence
 const store4 = kv(yourOwnStore); // Create a store based on your code
-// Many more here
+// Many more clients available
 ```
 
 These are all the methods of the [API](#api) (they are all `async`):
 
 - [`.get(key)`](#get): read a single value, or `null` if it doesn't exist or is expired.
 - [`.set(key, value, options?)`](#set): save a single value that is serializable.
-- [`.add(value, options?)`](#add): same as `.set()`, but auto-generates the key.
-- [`.has(key)`](#has): check whether a key exists or not.
-- [`.del(key)`](#del): delete a single value from the store.
-- [`.keys()`](#keys): get a list of all the available strings in the store.
-- [`.values()`](#values): get a list of all the values in the store.
-- [`.entries()`](#entries): get a list of all the key-value pairs.
-- [`.all()`](#all): get an object with the key:values mapped.
+- [`.add(value, options?)`](#add): save a single value with an auto-generated key.
+- [`.has(key)`](#has): check whether a key exists and is not expired.
+- [`.del(key)`](#del): delete a single key/value from the store.
+- [Iterator](#iterator): go through all of the key/values one by one.
+- [`.keys()`](#keys): get a list of all the available keys in the store.
+- [`.values()`](#values): get a list of all the available values in the store.
+- [`.entries()`](#entries): get a list of all the available key-value pairs.
+- [`.all()`](#all): get an object of all the key:values mapped.
 - [`.clear()`](#clear): delete ALL of the data in the store, effectively resetting it.
 - [`.close()`](#close): (only _some_ stores) ends the connection to the store.
 - [`.prefix(prefix)`](#prefix): create a sub-store that manages the keys with that prefix.
 
-> This library has very high performance with the item methods (GET/SET/ADD/HAS/DEL). For other methods or to learn more, see [the performance considerations](#performance) and read the docs on your specific client.
-
 Available clients for the KV store:
 
 - [**Memory** `new Map()`](#memory) (fe+be): an in-memory API to keep your KV store.
 - [**Local Storage** `localStorage`](#local-storage) (fe): persist the data in the browser's localStorage.
 - [**Session Storage** `sessionStorage`](#session-storage) (fe): persist the data in the browser's sessionStorage.
-- [**Cookies** `"cookie"`](#cookies) (fe): persist the data using cookies
-- [**LocalForage** `localForage`](#local-forage) (fe): persist the data on IndexedDB
-- [**Fetch API** `"https://..."`](#fetch-api) (fe+be): call an API to save/retrieve the data
-- [**File** `"file:///[...].json"`](#file) (be): store the data in a single JSON file in your FS
-- [**Folder** `"file:///[...]/"`](#folder) (be): store each key in a folder as json files
-- [**Redis Client** `redisClient`](#redis-client) (be): use the Redis instance that you connect to
-- [**Cloudflare KV** `env.KV_NAMESPACE`](#cloudflare-kv) (be): use Cloudflare's KV store
-- [**Level** `new Level('example', { valueEncoding: 'json' })`](#level) (fe+be): support the whole Level ecosystem
+- [**Cookies** `"cookie"`](#cookies) (fe): persist the data using cookies.
+- [**LocalForage** `localForage`](#local-forage) (fe): persist the data on IndexedDB.
+- [**Redis** `redisClient`](#redis) (be): use the Redis instance that you connect to.
+- [**SQLite** `sqlite`](#sqlite) (be): use a SQLite instance with a table called `kv`.
+- [**Fetch API** `"https://..."`](#fetch-api) (fe+be): call an API to save/retrieve the data.
+- [**File** `"file:///[...].json"`](#file) (be): store the data in a single JSON file in your FS.
+- [**Folder** `"file:///[...]/"`](#folder) (be): store each key in a folder as json files.
+- [**Cloudflare KV** `env.KV_NAMESPACE`](#cloudflare-kv) (be): use Cloudflare's KV store.
+- [**Postgres** `pool`](#postgres) (be): use PostgreSQL with the pg library.
+- [**Level** `new Level('example', { valueEncoding: 'json' })`](#level) (fe+be): support the whole Level ecosystem.
 - [**Etcd** `new Etcd3()`](#etcd) (be): the Microsoft's high performance KV store.
-- [**Postgres** `pool`](#postgres) (be): use PostgreSQL with the pg library
-- [**Prisma** `prisma.store`](#prisma) (be): use Prisma ORM as a key-value store
 - [**_Custom_** `{}`](#creating-a-store) (fe+be): create your own store with just 3 methods!
 
-I made this library to be used as a "building block" of other libraries, so that _your library_ can accept many cache stores effortlessly! It's universal (Node.js, Bun and the Browser) and tiny (~3KB). For example, let's say you create an API library, then you can accept the stores from your client:
+I made this library to be used as a "building block" of other libraries, so that _your library_ can accept many cache stores effortlessly! It's universal (Node.js, Bun and the Browser), idempotent (`kv(kv(A))` ~= `kv(A)`) and tiny (~4KB). For example, let's say you create an API library, then you can accept the stores from your client:
 
 ```js
 import MyApi from "my-api";
@@ -79,7 +78,7 @@ const REDIS = process.env.REDIS_URL;
 const store = kv(createClient({ url: REDIS }).connect());
 ```
 
-Now your store is ready to use! Add, set, get, del different keys. [See full API](#api).
+This follows the recommended naming, the default exported `kv()` for the base function, then `store` for the store instance. Now your store is ready to use! Add, set, get, del different keys. [See full API](#api).
 
 ```js
 const key = await store.add("Hello");
@@ -92,7 +91,7 @@ await store.del(key);
 
 ## API
 
-See how to initialize each store [in the Clients list documentation](#clients). But basically for every store, it's like this:
+The base `kv()` initialization is shared across clients ([see full clients list](#clients)); single argument that receives the client or a string representing the client:
 
 ```js
 import kv from "polystore";
@@ -103,9 +102,10 @@ const store = kv(MyClientOrStoreInstance);
 // use the store
 ```
 
-The above represents the recommended naming; the default export, `kv` in this case, is a wrapper that will generate a "store" that then you use all around your codebase.
+> [!IMPORTANT]
+> The library delivers excellent performance for item-level operations (GET, SET, ADD, HAS, DEL). For other methods or detailed guidance, check the performance considerations and consult your specific client’s documentation.
 
-You can enforce the **types** for the store values directly at the store creation, or at the method level:
+You can enforce **types** for store values either at store creation or at the method level:
 
 ```ts
 const store = kv<number>(new Map());
@@ -122,9 +122,12 @@ store.set<number>("abc", 10);
 store.set<number>("abc", "hello"); // FAILS
 ````
 
-> If you try to enforce data structure at _both_ the store level AND method level, then the method data type _should_ be a subclass of the store data structure, e.g. `kv<string | number>().get<string>("a")` will work, but `kv<string>().get<number>("a")` will _not_ work.
+> [!WARNING]
+> If you enforce types at _both_ the store level and method level, the method type must be a subset of the store type. For example, `kv<string | number>().get<string>("a")` works, but `kv<string>().get<number>("a")` _won't work_.
+
+Store values must be JSON-like data. The Serializable type represents values composed of `string`, `number`, `boolean`, `null`, and `arrays` and plain `objects` whose values are serializable. Class instances or non-plain objects will lose their prototypes and methods when stored.
 
-The type should always be `Serializable`, which is `number | string | boolean | Object | Array` (values can be `null` inside Object+Array). These types, along with the Store and Client, are exported as well:
+These are the exported types, `Client`, `Serializable` and `Store`:
 
 ```ts
 import kv from "polystore";
@@ -137,9 +140,9 @@ const value: Serializable = store.get('hello');
 
 ### .get()
 
-Retrieve a single value from the store. Will return `null` if the value is not set in the store, or if it was set but has already expired:
+Retrieves a single value from the store. If the key has never been set, was deleted, or has expired, it returns `null`:
 
-```js
+```ts
 const value = await store.get(key: string);
 
 console.log(await store.get("key1"));  // "Hello World"
@@ -147,13 +150,75 @@ console.log(await store.get("key2"));  // ["my", "grocery", "list"]
 console.log(await store.get("key3"));  // { name: "Francisco" }
 ```
 
-If the value is returned, it can be a simple type like `boolean`, `string` or `number`, or it can be a plain `Object` or `Array`, or any combination of those.
+You can specify the type either at [the store level](#api) or at the method level:
+
+```ts
+console.log(await store.get<string>("key1"));  // "Hello World"
+console.log(await store.get<string[]>("key2"));  // ["my", "grocery", "list"]
+console.log(await store.get<User>("key3"));  // { name: "Francisco" }
+```
+
+<details>
+  <summary>The value and its types must be <b>Serializable</b></summary>
+
+The value returned by `.get()` must be **serializable**. Valid types include:
+
+* `string`, `number`, `boolean`
+* Arrays or plain objects whose values are themselves serializable
+* Nested `null` values are allowed
+
+Class instances or non-plain objects will lose their prototypes and methods when stored. Only JSON-serializable data is safe. Examples:
+
+```ts
+// Valid
+type ValueType = string;
+type ValueType = string | number;
+type ValueType = { id: number; name: string; age: number | null };
+
+// Invalid
+type ValueType = Date;      // Loses prototype
+type ValueType = null;      // Only allowed as nested value
+type ValueType = Infinity;  // Not serializable
+```
+
+In short, only JSON-serializable data is safe to store.
+</details>
+
+When there's no value (either never set, deleted, or expired), `.get()` will return `null`:
+
+```ts
+// Never set
+console.log(await store.get("key1"));   // null
+
+// Deleted
+await store.set("key2", "Hello");
+console.log(await store.get("key2"));   // "Hello"
+await store.del('key2');
+console.log(await store.get("key2"));   // null
+
+// Expired
+await store.set("key3", "Hello", { expires: '1s' });
+console.log(await store.get("key3"));   // "Hello"
+await new Promise((done) => setTimeout(done, 2000)); // Wait 2 seconds
+console.log(await store.get("key3"));   // null (already expired)
+```
+
+> [!WARNING]
+> Attempting to read an expired key that wasn't automatically evicted will trigger a delete internally. This should not affect you directly, but it's good to know since you might expect a `read` operation not to modify the underlying data. See the [Eviction](#eviction) section and your specific client for details.
+
+If you are using a substore with `.prefix()`, `.get()` will respect it:
+
+```ts
+const session = store.prefix('session:');
+
+console.log(await session.get('key1')); 
+// Same as store.get("session:key1")
+```
 
-When there's no value (either never set, or expired), `null` will be returned from the operation.
 
 ### .set()
 
-Create or update a value in the store. Will return a promise that resolves with the key when the value has been saved. The value needs to be serializable:
+Create or update a value in the store. Will return a promise that resolves with the key when the value has been saved:
 
 ```js
 await store.set(key: string, value: any, options?: { expires: number|string });
@@ -163,7 +228,39 @@ await store.set("key2", ["my", "grocery", "list"], { expires: "1h" });
 await store.set("key3", { name: "Francisco" }, { expires: 60 * 60 });
 ```
 
-The value can be a simple type like `boolean`, `string` or `number`, or it can be a plain `Object` or `Array`, or a combination of those. It **cannot** be a more complex or non-serializable values like a `Date()`, `Infinity`, `undefined` (casted to `null`), a `Symbol`, etc.
+You can specify the type either at [the store level](#api) or at the method level:
+
+```ts
+await store.set<string>("key1", "Hello World");
+await store.set<string[]>("key2", ["my", "grocery", "list"]);
+await store.set<User>("key3", { name: "Francisco" });
+```
+
+<details>
+  <summary>The value and its types must be <b>Serializable</b></summary>
+
+The value returned by `.get()` must be **serializable**. Valid types include:
+
+* `string`, `number`, `boolean`
+* Arrays or plain objects whose values are themselves serializable
+* Nested `null` values are allowed
+
+Class instances or non-plain objects will lose their prototypes and methods when stored. Only JSON-serializable data is safe. Examples:
+
+```ts
+// Valid
+type ValueType = string;
+type ValueType = string | number;
+type ValueType = { id: number; name: string; age: number | null };
+
+// Invalid
+type ValueType = Date;      // Loses prototype
+type ValueType = null;      // Only allowed as nested value
+type ValueType = Infinity;  // Not serializable
+```
+
+In short, only JSON-serializable data is safe to store.
+</details>  
 
 - By default the keys _don't expire_.
 - Setting the `value` to `null`, or the `expires` to `0` is the equivalent of deleting the key+value.
@@ -648,7 +745,7 @@ console.log(await store.get("key1"));
   </ul>
 </details>
 
-### Redis Client
+### Redis
 
 Supports the official Node Redis Client. You can pass either the client or the promise:
 
@@ -676,6 +773,86 @@ You don't need to `await` for the connect or similar, this will process it prope
   </ul>
 </details>
 
+
+
+### SQLite
+
+Supports both **`bun:sqlite`** and **`better-sqlite3`** directly. Pass an already-opened database instance to `kv()` and Polystore will use the `kv` table to store keys, values, and expirations:
+
+> [!IMPORTANT]
+> The table `kv` will be created if it doesn't already exist
+
+```js
+import kv from "polystore";
+import Database from "better-sqlite3";
+// Or: import Database from "bun:sqlite";
+
+const db = new Database("data.db")
+const store = kv(db);
+
+await store.set("key1", "Hello world", { expires: "1h" });
+console.log(await store.get("key1"));
+// "Hello world"
+```
+
+<details>
+  <summary>Why use polystore with <code>SQLite</code>?</summary>
+  <p>These benefits apply when wrapping a SQLite DB with polystore:</p>
+  <ul>
+    <li><strong>Intuitive expirations</strong>: specify expiration times like <code>10min</code> or <code>2h</code> without manual date handling.</li>
+    <li><strong>Substores</strong>: use prefixes to isolate sets of keys cleanly.</li>
+    <li><strong>Simple persistence</strong>: full on-disk durability with a minimal driver.</li>
+  </ul>
+</details>
+
+#### SQLite schema
+
+This is the required schema:
+
+```sql
+CREATE TABLE kv (
+  id TEXT PRIMARY KEY,
+  value TEXT,
+  expires_at INTEGER
+);
+```
+
+You can create these with failsafes to make it much easier to initialize:
+
+```js
+db.exec(`
+  CREATE TABLE IF NOT EXISTS kv (
+    id TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    expires_at INTEGER
+  )
+`);
+db.exec(
+  `CREATE INDEX IF NOT EXISTS idx_kv_expires_at ON kv (expires_at)`,
+);
+````
+
+#### SQLite expirations
+
+If `expires` is provided, Polystore will convert it to a timestamp and persist it in `expires_at`. We handle reading/writing rows and expiration checks.
+
+However, these are not auto-evicted since SQLite doesn't have native expiration eviction. To avoid having stale data that is not used anymore, it's recommended you set a periodic check and clear expired records manually.
+
+There's many ways of doing this, but a simple/basic one is this:
+
+```js
+// Clear expired keys once every 10 minutes
+setInterval(() => {
+  db.prepare(`DELETE FROM kv WHERE expires_at < ?`).run(Date.now());
+}, 10 * 60 * 1000);
+````
+
+Note that Polystore is self-reliant and won't have any problem even if you don't set that script, it will never render a stale record. It's just for both your convenience and privacy reasons.
+
+
+
+
+
 ### Fetch API
 
 Calls an API to get/put the data:
@@ -910,6 +1087,7 @@ You'll need to be running the etcd store for this to work as expected.
   </ul>
 </details>
 
+
 ### Postgres
 
 Use PostgreSQL with the `pg` library as a key-value store:
@@ -962,45 +1140,6 @@ This maps prefixes to table names for better performance on group operations.
   </ul>
 </details>
 
-### Prisma
-
-Use Prisma as a key-value store by passing a table model directly:
-
-```js
-import kv from "polystore";
-import { PrismaClient } from "@prisma/client";
-
-const prisma = new PrismaClient();
-const store = kv(prisma.session);
-
-await store.set("key1", "Hello world", { expires: "1h" });
-console.log(await store.get("key1"));
-// "Hello world"
-```
-
-Your Prisma schema needs a model with three columns: `id` (String), `value` (String/Text), and `expiresAt` (DateTime, nullable):
-
-```prisma
-model session {
-  id        String    @id
-  value     String    @db.Text
-  expiresAt DateTime?
-}
-```
-
-All three columns are required. The `expiresAt` column should be nullable (`DateTime?`) to support records without expiration.
-
-<details>
-  <summary>Why use polystore with Prisma?</summary>
-  <p>These benefits are for wrapping Prisma with polystore:</p>
-  <ul>
-    <li><strong>Unified API</strong>: use the same API across all your storage backends.</li>
-    <li><strong>Database-backed persistence</strong>: leverage your existing database for key-value storage.</li>
-    <li><strong>Intuitive expirations</strong>: use plain English to specify the expiration time like <code>10min</code>. <a href="#expiration">Expirations</a>.</li>
-    <li><strong>Substores</strong>: you can also create substores and manage partial data with ease. <a href="#prefix">Details about substores</a>.</li>
-  </ul>
-</details>
-
 ### Custom store
 
 Please see the [creating a store](#creating-a-store) section for all the details!