polystore 0.16.0 → 0.16.1

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

@@ -431,22 +431,8 @@ var SQLite = class extends Client {
   //  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
-    );
+    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 +443,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,29 +461,24 @@ 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`);
@@ -686,6 +661,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 +685,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 +752,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 +789,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 +811,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 +833,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.16.1",
   "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",

package/readme.md

@@ -910,6 +910,80 @@ You'll need to be running the etcd store for this to work as expected.
   </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` must already exist in the Database
+
+```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"
+```
+
+### 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.run(`
+  CREATE TABLE IF NOT EXISTS kv (
+    id TEXT PRIMARY KEY,
+    value TEXT NOT NULL,
+    expires_at INTEGER
+  )
+`);
+db.run(
+  `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 a native expiration. To avoid having stale data that is not used anymore, it's recommended you set a periodic check and clear expired records manually:
+
+```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.
+
+<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>
+
+
 ### Postgres
 
 Use PostgreSQL with the `pg` library as a key-value store: